REST CONFIGLETS

Contents What are REST Configlets Adding a device to REST API support Applying REST credentials to a device Steps to use REST configlets REST configlets - Execution results REST configlets - Benefits

What are REST Configlets?

A REST API is an application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows interaction with RESTful web services. When it comes to configurations, most of the device vendors provide REST API support on different levels for reading and writing the device configuration in parts or as a whole during the backup process.

Network Configuration Manager uses the REST APIs to allow users to have a simplified UI experience. The users can focus on a particular part of the configuration without worrying about the command syntax and configuration hierarchy. On top of that, the REST API's GUI has been designed to resemble the device GUI for users' better understanding.

In NCM, REST API based configuration management works with REST Configlets.Rest configlets are configuration objects such as address, policy, security rules etc. You can access Rest Configlets by going to Config Automation > Configlets > Rest Configlets (In case of OPM or NFA, this option is available under Settings > NCM > Configlets > REST Configlets).

Each configlet comes with a different set of operations such as Add, Edit, View, Delete, Rename, View All, Clone, Execute etc.

Operation	Description
Add	Adds a new object to the device configuration.
Edit	Provides a list of objects available in the device. Users can then select a particular object. The details about the selected object will be fetched from the device and will be shown to the users. Users can update any particular detail/parameter for that object and then execute the configlet to save the changes in device.
View	Provides a list of objects available in the device. Users can then select a particular object. The details about the selected object will be fetched from the device and shown to the user in read only mode.
View All	Shows all the available objects in the device in a grid along with their details
Delete	Provides a list of objects available in the device. Users can select a particular object and execute the configlet to delete the object.
Rename	Users can select a particular object and provide a new name to rename the object in the device.
Clone	Users can select a particular object and provide a new name to clone the object in the device with the name provided along with its properties
Execute	Most of the non-firewall devices have objects that can only be viewed and executed as CLI commands. For such devices and configuration objects, there will be only one operation available, which is "Execute". It will execute the command in the device with the provided parameters.

Adding a device to REST API support

A device with REST API support can be added by following the steps given below:

• Go to Inventory > Devices.
• Click on add icon on top right corner.
• Enter the host name or IP Address of the device.
• Select a device Vendor.
• Select the appropriate device template for the device.
• Add Series, Model and Custom Column information (optional).
• Click on the "Add" button.

Once the device is added, you need to provide credentials on the next slide. you can either provide just REST Credentials or a combination of CLI and REST Credentials. NCM recommends to use the combination of CLI and REST credentials to make the most out of the tool. Please follow the steps given below to associate the credentials to the device:

• To use just the REST credentials, please select REST API from protocol dropdown. (Note: This option is available only for selected device templates). To use the combination of REST and CLI credentials, please select any other protocol.
• For CLI credentials please provide credentials under Primary and Additional tab. (These tabs will not be available if the REST API protocol is selected in the first step).
• To provide REST credentials please open the REST API tab.
• When a CLI protocol is chosen, you need to first check the option to use REST API credentials under this tab to see the rest of the parameters. Please check the "Use rest API for communication whenever applicable" checkbox.
• Select the protocol that needs to be used to connect to the device (http / https ).
• Enter values for the rest of the required parameters. (These parameters will be different for each device template. A Few fields will be populated with default values which can be changed according to device requirement).
Click on the "Save" button.

Note :

• As of now the "Save and Test" option does not work for REST credentials.
• REST API is supported only for selected vendors for now, however you are continuously trying to support more vendors.
• In case of any queries, please reach out to NCM support team at ncm-support@manageengine.com

Applying REST credentials to a device

You can either provide just REST Credentials or a combination of CLI and REST Credentials. NCM recommends to use the combination of CLI and REST Credentials to make the most out of the tool. Please follow the steps given below to associate the credentials to the device:

• Go to Inventory > Devices
• Click on the credential icon of the device to which the credentials needs to be associated. Alternatively, you can select the device and select the "Apply Credentials" option from more options.



• To use just REST credentials, please user REST API from protocol dropdown. (Note: This option is available only for selected device templates). To use the combination of REST and CLI credentials please select any other protocol.
• For CLI credentials please provide credentials under Primary and Additional tab. (These tabs will not be available if the REST API protocol is selected in the first step).
• To provide REST credentials please open the REST API tab.
• When a CLI protocol is chosen, you need to first check the option to use REST API credentials under this tab to see the rest of the parameters. Please check the "Use rest API for communication whenever applicable" checkbox.
• Select the protocol that needs to be used to connect to the device (http / https ).
• Enter values for the rest of the required parameters. (These parameters will be different for each device template. Few of the fields will be populated with default values which can be changed according to device requirement).
• Click on the "Save" button.

Note :

• As of now the "Save and Test" option does not work for REST credentials.
• REST API is supported only for selected vendors for now, however you are continuously trying to support more and more devices.
• In case of any queries, please reach out to NCM support team at ncm-support@manageengine.com

Steps to use REST configlets

To use REST configlets you need to fist add a device with REST API support to NCM. Please click here to know more about how to add a device and associate REST credentials to it.

Once a device is added and Rest Credentials are associated with the device, you can either use the REST Configlets page under Config Automation tab (For non OPM and NFA these this page will be under Settings > NCM > Configlets) or Object Explorer option under Device snapshot page to use REST Configlets. To know what are REST Configlets please click here.

REST Configlet page:

• Please go to Config Automation > Configlets > REST Configlets (only if you are using NCM, in case of OPM and NFA please go to Settings > NCM > Configlets > REST Configlets).
• You can filter the list of configlets based on your vendor by entering the vendor name in the search box under the Vendor header. (If the search box is not visible please click on the search icon on the grid header).
• The list of configlets may vary for different vendors.
• Each configlet is either an operation in itself and will have only "Execute" operation or is an object (Address, policy, schedule etc.) from device configuration and will have multiple operations (Add, Edit, Delete, View etc).
• Select an operation for a particular object and provide the required params on the newly opened slide and click on Execute to make the changes to the device configuration. (A Few operations are read-only and won't have the Execute option. You will have to select the device before performing any operation. In case of any update / delete operation, please select an object from the list of objects fetched from the device).

Object Explorer:

• Go to Inventory > Devices
• Click on any of the devices to open the device snapshot page.
• If the selected device supports the REST API operations, an option called Object explorer will be presented in the device snapshot page . This is a list of object types (Address, Policy, Schedule etc) from device configuration.
• Once any of the object types is selected from the Object Explorer list, a new slide will open with the list of objects of the selected type.
• Here you can select any of the objects from the grid and click on "Hamburger icon" on top right of the grid to see the list of operations that can be performed on the selected object.
• Add and delete operations are available on top of the grid (These operations will be available only if Add and/or delete operations are supported).
• Once an operation is selected, a new slide will open to execute the operation.
• Provide required parameters in the newly opened slide and click on execute. (This option will be available only if the operation is not read-only)

Note : Device must be up and running to run any device configlets

REST configlets - Execution results

Please follow the steps given below to check the result of REST Configlets Execution.

• Go to Config Automation > Configlets > REST Configlets History (In case of OPM or NFA, this option is available under Settings > NCM > Configlets > REST Configlets History)
• Here you can see the list of Configlets Execution with their status.
• You can also click on any of the rows to see more detailed information in a sub grid.
• In the sub grid you can click on pdf or csv icons to get a report with the device response.
• Alternatively, you can click on the sub grid row to open a slide with the device response and also view the difference between the object values before and after execution (difference is available only in case of edit).

How to check if NCM supports REST operations for my device or not?

Please go to Config Automation > Device Templates > REST Device Templates and see if there is a device template available for your device. If yes, then you can perform REST operations using NCM on that particular device. For OpManager and NFA this page is available under Settings > NCM REST Device Templates.

Please note: Make sure the device's firmware version is higher than or equal to the base OS version for REST operations to work properly.

REST configlets - Benefits

• While backing up whole configurations, REST APIs are much faster than a normal CLI backup. In fact all REST API operations are faster than CLI operations in general.
• One does not have to memorize command syntaxes while updating a particular part of a configuration.
• One does not have to worry about the hierarchy of objects in a configuration.
• The important objects in a configuration can be viewed in a grid format in NCM.
• NCM's REST Configlet feature provides a GUI that is similar to the device's GUI (Eg: Firewall GUI) and this makes it easy to update a part of the configuration directly from NCM.