Example of creating a custom action adapter using UI

Example: Capture device information using a Ping custom action, reporting results into job status

The Ping custom action is a basic example of how to request input from a custom action user, with runtime parameters. The user’s input is plugged into the ping command executed at the device.

If the ping command fails, the completion status of the custom action (and the enclosing job) depends on the result of the ping (Success on complete success, Failed on a complete failure, or Succeeded with warning on a partial failure). 

This example is a simplified version of the standard Ping custom action, which is available on the Device Adapters page and is implemented for many device types. In this example, the Ping action is implemented for the Cisco IOS device type.

Adding the custom action

On the Admin > Network Admin > Device Adapters page, click Add > Custom Action, and do the following:

1. On the Declaration tab, enter the following information:
   • In Name, enter a name for the custom action, for example, Ping.
   • From Menu Group, select the name of the group, for example, Diagnostics, which defines the group or category of this custom action.
   • In Description, enter a description, for example, Pings from the device to the IP address entered at runtime.
   • In General Information, enter notes, warnings, quirks, or anything else special about this custom action that might affect how users use it. 
     This information will be displayed in the Device Adapter Capabilities report.
   • Select the following options if not selected by default:
     • Browser Executable: Indicates that this custom action can be executed from the UI. 
     • Inspection Only: Indicates that the custom action does not make any changes to the device. 

1. • Scroll down to the Runtime Parameters section and add the runtime parameter:

     1. Click Add and enter the following information:
        1. In Result Property Name, enter the name of the runtime parameter, for example, node.
        2. In Display Label, enter the message to be displayed to the users, telling the users what needs to be entered. For example, enter IP Address of the Node to Ping.
        3. Select the Value Is Required option to indicate that it is mandatory to enter the value of this runtime parameter.
        4. In Sort Order, enter the sort order as 1.
        5. From Type, select the type of the parameter as Text.
        6. In Validation Mask, enter a regular expression that the user-entered text must match in order to be considered valid. 
           For example, enter \d+\.\d+\.\d+.\d+. This expression checks a simple IPv4 address.
        7. Click Save.

     

2. Click the Implementation(s) tab, and click Add Device Type to add information about a device type for which the custom action should be applicable. 

1. From Vendor, select Cisco, and from Device Type, select Cisco IOS Switch/Router to indicate that custom action will be applicable to Cisco IOS Switch/Router.

2. Click Main Logic Elements, and add elements for the custom action.

   1. Add the Interaction element.

      1. Click + Interaction.
      2. From the Attributes list, select the Treat Prompt, Response, and Error Elements as Regular Expressions attribute to include this attribute. 
      3. Select the Treat Prompt, Response, and Error Elements as Regular Expressions checkbox to indicate that the Prompt, Response, or Error elements must be treated as regular expressions.
      4. Select the Prompt checkbox to include this element.
      5. Select the Response checkbox, and click + and increase the counter to 3 to include 3 Response elements.
      6. Click Save.

      

   2. Click the Info icon next to the Interaction element and view the order and arrange the elements in that order by dragging elements.
      
   3. Add values to the Prompt, Command, and Response elements.
      1. In the Element Group Name column, expand the Interaction element.
      2. Click the + (Edit) icon next to the Prompt element.
      3. In Content, enter the following string: %prompt%
         
         
      4. Click Save.
      5. Click the + (Edit) icon next to the Command element.
      6. In Content, enter the following string: ping%runtime.node%
         This command is to be run on the device, with a keyword to plug in the IP address entered by the user.
         
      7. Click Save.
      8. Click the + (Edit) icon next to the first Response element.
      9. In Content, enter the following string: Success rate is 100 percent
      10. In Property to Be Populated, enter the following string: cmd.pingSuccess
          
          
      11. Click Save.
      12. Click the + (Edit) icon next to the second Response element.
      13. In Content, enter the following string: Success rate is (20/40/60/80) percent
      14. In Property to Be Populated, enter the following string: cmd.pingWarning
          
          
      15. Click Save.
      16. Click the + (Edit) icon next to the third Response element.
      17. In Content, enter the following string: Success rate is 0 percent
      18. In Property to Be Populated, enter the following string: cmd.pingAbort
          
          
      19. Click Save.
   4. Add the first Assert element.
      1. Click Assert.
      2. In Assertion Failure Message, add the following string: Ping returned success rate of 0 percent.
      3. From the Attributes list, select On Failure to include this attribute.
      4. In Condition, add the following string: ((-EXISTS- cmd.pingSuccess) -OR- (-EXISTS- cmd.pingWarning))
         This condition checks if properties, cmd.pingSuccess or cmd.pingWarning exist (from being set in the preceding lines); if not, causes this action to fail with an error.
      5. From On Failure, select Show Action as Failed. 
         
      6. Click Save.
   5. Add the second Assert element.
      1. Click Assert.
      2. In Assertion Failure Message, add the following string: Ping returned success rate of greater than 0 but less than 100 percent.
      3. From the Attributes list, select On Failure to include this attribute.
      4. In Condition, add the following string: (-EXISTS- cmd.pingSuccess)
         This condition checks if property cmd.pingSuccess exists; if not, causes this action to to fail with a warning. Else, processing continues on; since there is nothing else to do, the action completes successfully.
      5. From On Failure, select Show Action as Succeeded With Warning.
         
      6. Click Save.

   

3. Click Enter to finish adding implementation of the device type.

1. (Optional) On the Implementation(s) tab, click Add Device Type to add information about another device type for which the custom action should be applicable. 

1. (Optional) Once you are done adding elements, click Preview on top of the page to preview the device adapter XML. See Preview of the custom action adapter XML for the benefits of the preview option.
2. Click Save on the top of the page.

Back to top

Recommendations to direct the custom action results 

The results of executing a custom action can be directed to the following locations:

• The custom action's completion status (as shown in the preceding example)
• The custom action's execution transcript
• The Captured results column in the Job Details report
• Device dynamic fields
• Imported hardware inventory

 When determining which location to direct the custom action results, use the following recommendations: 

• Job status: Use alone for simple checks whose result can be evaluated to success or failure. Use with other techniques for more complicated actions.
• Transcripts: Use for long lists containing a lot of data that you want to review, or for transient reports gathering statistics or low-level operational states (for example, run a show ipc queue every 24 hours and report the results). Custom action transcripts can be attached to job email notifications and included in the Job Details exported and emailed versions, when you choose to include all details. The Print View version of the Job Details page also displays all the transcripts in the job.
• Captured results: Use for small amounts of data that you want parsed out of longer show command results and presented in the Job Details page. Also, use captured results for custom actions that you use often (for example, show current vlans defined on all switches). A captured result is limited to 2000 characters.
• Dynamic fields: Use for small bits of persistent information that do not change often (for example, serial numbers, uplink interfaces, and so on). Dynamic field values are limited in length, but a device can have many dynamic fields and a field can have either a single value or multiple values. Devices can be auto-grouped on the value, and the value can be referenced by templates, compliance rules, and other custom actions as a device substitution parameter. The value can be viewed and exported using the Device inventory report. A Text type of dynamic field limits the value to 2000 characters; other dynamic fields impose a limit to 255 characters. See Adding dynamic fields.
• Imported inventory: Use for a single large blob of information related to the hardware installed on the device that does not change very often (for example, the output of the IOS show module command). A device has a single imported inventory that can be viewed when you view or edit a device, and viewed and exported from the Device Inventory report. The size of the imported inventory is unlimited.

Back to top