How do I create, view, manage or delete a configuration task?

Introduction to configuration management tasks

To create a new configuration management task

To view configuration management tasks

To copy a configuration management task

To edit a configuration management task

To import configuration management tasks

To export configuration management tasks

To delete a configuration management task

Introduction to configuration management tasks

The Configuration Management page is where you can create, edit or delete a configuration task.

Note: in multi-server configuration, configuration monitoring tasks (configuration retrieval) must exist on the remote pollers on which the relevant devices are managed.

Entuity uses a combination of the Entuity information database, an Expect API and Groovy scripts to allow you to specify configuration tasks. A configuration task contains all the instructions required to complete the designated configuration management or monitor task. Tasks can be initiated from a Context Menu (from Entuity v20.0 upwards, these configuration management options are grayed out in the context menu if the device is unlicensed for configuration management) or through the scheduler.

Configuration management tasks provide CLI (SSH or Telnet) communications automation capabilities, but can also be used for other purposes. A task usually has a specific objective, which is often the configuration of a device or port. It involves a number of steps.

For example:

1. log in to a device.
2. perform an action.
3. log out of a device.

The login and logout steps are generic and could be reused by many tasks.

When you run a task, it becomes a job. If this job is running against a number of objects (devices or ports), then each object has its own sub-job. Therefore, the success or failure of a subjob on one object does not impact the processing of another subjob.

Configuration management task process:

The configuration management task process is as follows:

1. Task is run.
2. The Entuity server identifies and validates the target objects. 
   Where the target objects are managed by remote Entuity servers, this involves checking with those servers and potentially amending the list of targets against which the job runs. The validation tests that are applied before dispatching the job are as follows:
   1. Check that the task is still available.
   2. Check that the current version of the task is the same as that associated with the job, for example, one user might call a task while another is updating it. This check is only applicable to tasks called from context menus.
   3. Validate the Groovy script.
   4. Check that the user permissions of job owner are sufficient to run the job.
   5. Apply the filter to derive the target objects.
3. The Entuity server creates a dispatch job to send to the Script Engine of the Entuity server that is managing the target objects. 
   The dispatch job contains one sub-job for each target. When these targets are managed by different servers, Entuity creates a dispatch job for each server. 
   Note, because jobs might be defined on a central server but run on a remote server, it is important that central and remote servers are running the same version of Entuity.
4. The Script Engine runs the sub-jobs, performing the specified task on the target device or port. 
   Through the Job History page, you can view the progress of a job, and you can drill down to a sub-job to view its progress. When tasks are configured for events, then Entuity can raise events and incidents that report the success or failure of the job.

You can also use the Entuity RESTful API to apply configuration management settings to one or more specified devices.

Context of configuration management job events:

You can run a configuration management job against multiple devices, which means that the Config Mgmt Job Succeeded or Config Mgmt Job Failed events exist in the 'My Network' View level context, and not in the context of an individual device.

Therefore, if you write and run a configuration management job against a single device, you won't see the success or failure event(s) for that job in the context of that device. They are only visible at the 'My Network' View level.

To create a new configuration management task:

1. From the Main Menu, click Administration and then click Configuration Management.
   The Configuration Management page is displayed.
2. From the Tasks tab of the Configuration Management page, click New.
   
   
    
   The New Task form is displayed.
    
3. Enter the details of the task:
   
   
    
   1. Enter the Name and Description for the task in the respective fields, and specify the task's context in the Context drop down field (either a device or a port). 
      From Entuity v21.0 P01 upwards, a task name cannot contain the following characters: |, /, \, ", *, <, >.
      
      
   2. Add steps in the Steps field by clicking Add Step. 
      A configuration task consists of steps. You can add as many steps to the task as you want.
      
      
      From the Add Step form that opens, you can select from a list of existing steps, or click New Step at the bottom of the form to create a new custom step. Use ctrl or shift to select multiple steps at the same time, and click Done to return to the New Task form.
      
      
   3. Review the selected steps that are displayed.
      
      
      
      You can drag the steps into your preferred order, or click on a step to see further details or delete the step.
      
      
   4. Specify the Parameters for the task by clicking New Parameter. 
      Note, a saved parameter will then be available as a variable to all steps that are added to this task.
      
      
      The New Parameter form is displayed.
   5. Enter values for the new parameter:
      1. In the Name field, enter a name for the parameter, which must be a valid Groovy variable name, and must be unique for each task. 
         From Entuity v21.0 P01 upwards, you cannot set parameters that are already used by system configuration management tasks.
         These are:
         • transferMethod
         • transferServer
         • transferUsername
         • transferPassword.
           
           
            
      2. Enter a Description.
      3. Select a Data Type from the dropdown field, from the following:
         • String
         • Integer
         • Float
         • Firmware
         • Expanded String (Entuity v22.0 upwards)
         • Boolean (Entuity v22.0 upwards)
         • Archived Configuration (Entuity v22.0 upwards) - see this section for information on this type of parameter.
      4. Specify a Default Value - if specified, it must be a valid Groovy expression. If it's not specified, Entuity assigns null to the variable.
      5. Switch on Password Field if you want to asterisk characters when you enter them. If switched off (which is the default), then the characters are not masked.
      6. Switch on Always Prompt so that Entuity always prompts the user to enter a value. If switched off (default), Entuity does not prompt for a value, unless the default value is not set.
      7. Upon completing the form, click Done to save your changes and return to the New Task form. Otherwise, click Cancel.
         The parameter(s) are displayed in the Parameters field on the New Task form.
         
         
   6. Switch on Configuration Monitor Task if you want Configuration Monitor to handle the task as a configuration monitor task.
      Configuration monitor tasks:
      • are not displayed in the Task Permissions dialog. Instead, if a user has the Configuration Monitor tool permission, then the user implicitly has permission to run and view the history of all related configuration monitor tasks.
      • cannot be scheduled.
      • must be defined on each server on which the tasks will be used.
   7. Click Advanced Settings to open the Advanced Settings form.
      
      
      
      
       
      1. In the Job Timeout (seconds) field, specify the time, in seconds, assigned for Entuity to execute the task against one or multiple objects before the task will timeout and terminate. The default is 300 seconds (5 minutes).
      2. From Entuity v23 upwards, switch on Timeout per Object if you want the job timeout to be separate for each object against which the task is executed (or, on a per sub-job basis).
      3. Choose the method of connecting to the object from the Connection Method dropdown field:
         • use cli access parameters - use the connection method defined in the credential set.
         • use connection parameters - prompt the user for credential details before executing the task.
         • none - Entuity does not require a connection to complete the task, e.g. SNMP Get/Set only tasks.
      4. Switch on Non-Config Retrieval /Config Retrieval if the task will be for configuration retrieval.
         If Config Retrieval is switched on, the Supported Transfer Methods field and the (from Entuity v23 upwards) Filter characters from config comparison field are displayed.
      5. With the Supported Transfer Methods field, select from the available options:
         • TFTP
         • FTP
         • SCP PULL (from Entuity v21.0 P03 and v20.0 P08 upwards)
         • SCP PUSH (from Entuity v21.0 P03 and v20.0 P08 upwards)
           Note, SCP is available for versions of Entuity earlier than the above.
         • FTP
         • CLI
      6. With the Filter characters from config comparison field, specify a list of characters that you want excluded when you compare configuration files that are associated with the task. For more information on viewing the differences between configuration files, see this article.
      7. Switch on Raise Event on Completion if you want Entuity to raise a Config Mgmt Job Succeeded or Config Mgmt Job Failed event upon completing a job. 
         Note, Config Mgmt Job Succeeded and Config Mgmt Job Failed events are only visible at the 'My Network' View level context (see this note above for further information on this).
      8. Switch on Collect Diagnostic Data if you want Entuity to retain the conversation data between the script engine and the device for each task. From Entuity v21.0 P02 upwards, this is enabled by default.
         Script Engine retains the conversation data between itself and the device for each task (which can be turned off in entuity.cfg). There is a limit (configurable in entuity.cfg) of the total size of these diagnostic data that can be stored in Script Engine's log file (which is entuity_home\log\expect.log).
      9. In the Filter field, enter the object against which you want the task to legitimately run.
         • Object filter specifies the object against which the task can legitimately run, for example, you can filter on the device SysOid: 
           simple; device.sysOid==”1.3.6.1.2.1.1.3” ||
           device.sysOid==”1.3.6.1.2.1.1.4”
         • In multi-server environments, if the selected object is on a remote server, the filter is sent to the remote server for evaluation. The result is returned to the central server.
         • For context menus, a filter is evaluated when you open the menu, so if the selected object does not meet the filter then the context menu task is not displayed.
         • For scheduled jobs, the filter is always evaluated when the scheduled job is run.
      10. Switch on Show on Context Menu if you want the task to be run from the context menu.
      11. Switch on Show on View Selection if you want the task to be run from the View-level context.
      12. Switch on Confirm Execution to provide a confirmation dialog that appears when you execute a task, for example, from the right-click Context Menu:
          
          
           
      13. In the Selection Limit field, enter the maximum number of objects that can be selected when running the task from the context menu.
          • If the limit is set to 1, the task is only available from the context menu when 1 object is selected.
          • If the limit is set to N, the task is only available from the context menu when N or fewer objects are selected.
      14. Click Done on the Advanced Settings form to save your changes and return to the New Task form.
   8. When you have defined the task settings, click Done on the New Task form to save your changes. Otherwise, click Cancel.

To view configuration management tasks:

1. Navigate to the Configuration Management page, and click the Tasks tab.
   
   

2. Review the values in the table.
   The table lists all your system and custom configuration management tasks. 

   Column Name	Column Description
   Name	string to identify a task, which must be unique on the selected server (case insensitive comparison).
   Description	task description.
   Category	if the task is system or custom.
   Task Type	whether the task is a configuration monitor task or configuration management task.  Configuration monitor tasks: -do not appear in the Task Permissions dialog. Instead, if a user has the 'Configuration Monitor' tool permission, then they will implicitly have permission to run and view the history of all related configuration monitor tasks. -cannot be scheduled. -must be defined on each server on which they will be used.
   Context	context in which the task can run, for example, Device or Port.
   Transfer Methods	(Entuity v23.0 upwards) the transfer method to be used for the task.
   Steps	number of steps in the task.
   Schedules	number of scheduled jobs for this task.
   Last Edited	(Entuity v21.0 P02 upwards) timestamp of the last edit to the task.
   Last Run Time	timestamp of the last execution of the task.
   Last Run Status	if the task has an associated job that is running, then Last Run Status indicates the current state of jobs associated with the task. For example, 2 in progress, 3 queued. This is also a hyperlink to the Job History tab. if the task does not have an associated job that is running, then Last Run Status shows the state of the previously completed job, for example, Succeeded or Failed.

To copy a configuration management task:

You can copy system configuration management tasks. These copies are then considered custom tasks, and you can edit them as such.

1. Navigate to the Configuration Management page, and click the Tasks tab.
2. Select a task and then click Copy at the top of the tab (or from the Overflow Menu or right-click Context Menu).
   
   
   
   The copied task is displayed in the table below the original task.

To edit a configuration management task:

Note, you can only edit a custom configuration management task (this includes copies of a system configuration management task).

1. Navigate to the Configuration Management page, and click the Tasks tab.
2. Select a task and then click Edit at the top of the tab (or from the Overflow Menu or right-click Context Menu).
   
   
    
3. Edit the task settings on the Edit Task form that is displayed.
   The form has the same fields as when creating a new task.
4. Click Done to save your changes. Otherwise, click Cancel.