How do I import and export configuration management steps and tasks using files?

Directory hosting imported system step and task definitions

Required format of XML files

Importing system steps and tasks

To import custom steps and tasks via the command line

To export system and custom steps and tasks

To output help for importing and exporting steps and tasks

From Entuity v21.0 P01 upwards, you can:

• import and export custom configuration management steps and tasks using XML files via the command line.
• export system configuration management steps using XML files via the command line. Upon running configure after upgrading to Entuity v21.0 P01, system configuration management steps will be automatically imported.

Directory hosting imported system step and task definitions

The following directory on Entuity installs hosts the system imported configuration management steps and tasks:

<entuity_home>/etc/configurationamanagement/system

Required format of XML files:

• <configurationmanagement> - root element for the XML documentation.
  
  
  • • <step name="?" system="?"> - element required to define a step:
      step name - required, must be less than 64 characters.
      system - required, either "Y" (for a system step) or "N" (not a system step).
      • • <description> - description element for the step, maximum 128 characters.
        • <context> - context element for the step, can hold the values "port", "device" or "none".
        • <script> - groovy script element for the step, must contain a CDATA block with valid groovy script inside.
          
          
    • <task name="?" system="?"> - element required to define a task:
      task name - required, must be less than 64 characters.
      system - required, either "Y" (for a system task) or "N" (not a system task).
      
      • • <description> - description element for the task, maximum 128 characters.
        • <context> - context element for the task, can hold the values "port", "device" or "none".
        • <configmonitortask> - element indicating whether the task is a configuration monitor task, either "Y" (for a configuration monitor task) or "N" (not a configuration monitor task).
        • <associatedsteps> - element containing a list of steps associated with this task. These steps can be defined with the XML element below, and the element can be used as many times as you wish within <associatedsteps>...</associatedsteps>:
          
          • • <stepdef name="?" system="?"> - element linking a specific step to this task:
              stepdef name - name of the step, required, must be less than 64 characters.
              system - required, either "Y" (for a system step) or "N" (not a system step).
        • <parameters> - element defining a list of parameters that will be created for this task. These parameters can be defined with the XML element below, and the element can be used as many times as you wish within <parameters>...</parameters>:
          • • <parameter name="?"> - element defining this parameter:
              parameter name - required, must be less than 64 characters.
              • • <parameterdescription> - description element for this parameter, maximum 128 characters.
                • <datatype> - element describing the data type of the defaultvalue below, either "String", "Integer", "Float" or "Firmware".
                • <defaultvalue> - default value of this parameter, must be one of the format/data types described above in datatype, maximum 128 characters.
                • <passwordfield> - element indicating whether this parameter requires a password field, either "Y" (true) or "N" (false).
                • <alwaysprompt> - element indicating whether this parameter should always prompt a password field, either "Y" (true) or "N" (false).
        • <jobtimeout> - element specifying the job timeout for this task (in seconds), represented as an integer of maximum characters.
        • <connectionmethod> - element specifying the connection method used, either "use cli access parameters", "use connection parameters", or "none".
        • <supportedtransfermethods> - element specifying the supported transfer methods, either "TFTP", "FTP", "SCP PUSH", "SCP PULL", "SFTP" or "CLI". To use non-config retrieval, enter "none".
          
          • Note, "SCP PUSH" and "SCP PULL" are available from Entuity v21.0 P03 and v20.0 P08 upwards. "SCP" is available for earlier version of Entuity.
        • <eventoncompletion> - element indicating whether an event should be raised on completion of this task, either "Y" (true) or "N" (false).
        • <diagnose> - element indicating whether this task should have diagnostics mode on, either "Y" (true) or "N" (false).
        • <filter> - element defining a filter, must be valid. Data type of blob in the SQL tables, usually a "simple;..." debug agent/StormWorks-type command.
        • <menuname> - element defining the name that appears on the menu. If not specified, this will default to the task name element.
        • <showoncontextmenu> - element indicating whether this task should show on the context menu, either "Y" (true) or "N" (false).
        • <showonviewselection> - element indicating whether this task should show on View selection, either "Y" (true) or "N" (false).
        • <confirmexecution> - element indicating whether to confirm execution of this task, either "Y" (true) or "N" (false).
        • <selectionlimit> - element specifying the selection limit for this task, represented as an unsigned integer of maximum 10 characters.

Importing system steps and tasks:

System steps and tasks are automatically imported upon a user upgrading to a specific version of Entuity and running configure, with steps and tasks imported from the directory specified above.

Important note: Entuity recommends that you do not put anything into this folder, or delete this folder or any contents therein.

Import/export/deprecation logic:

• If an existing config management step or task is in use, and is set to be replaced by a newer imported step/task, the existing step/task will remain in use but be marked as deprecated.
• When the existing step/task is no longer being used (i.e. if the task is not scheduled, or if the step is not curently being used by a task), that step/task will be deleted and a copy placed in the archive folder, which by default is located here: <ENTUITY_HOME>\etc\configurationmanagement\archive.
• Note, due to improvements to pre-existing scripts/tasks by the Entuity Support team, some current steps and tasks might be marked as deprecated or deleted from the system. These can then be retrieved from the <ENTUITY_HOME>\etc\configurationmanagement\archive directory.
• To reimport a deprecated step/task:
  1. Navigate to the deprecated task in the above archive directory, and via the command line change it from a system task to a custom task (system="Y" to system="N").
  2. This task will consist of current system steps, therefore if you want to restore the deprecated steps with it, you will need (via the command line) to navigate to those steps and change those from system steps to custom steps (system="Y" to system="N").
  3. Copy over those existing steps to this deprecated task.
  4. Reimport the deprecated task from the command line.
• Note, the tasks in the archive directory will currently point to the newly imported steps - if you want to reimport using the command line and point to the old/deprecated steps, you will first have to import the old/deprecated steps and change what steps this xml file points to for this task before importing (see the <associatedsteps> tag in the Required format of XML files section above.
• Upon upgrades, any further deprecation of a step or task will replace any existing deprecated versions of that step or task already in the archive directory.

To import custom steps and tasks via the command line:

You can import custom steps and tasks using the following command in the command line:

%ENTUITY_HOME%\install\cmHelper.exe --import --ignore=[enabled/disabled] --path=$Path

or

%ENTUITY_HOME%\install\cmHelper.exe --import --ignore [enabled/disabled] --path $Path

For import commands, the specified file path can be one of the following:

• folder:
  ExampleDrive:\RandomFilePath\JustAnExample\Folder
  
  
• file:
  ExampleDrive:\RandomFilePath\JustAnExample\Folder\TheFile.xml
  
  
• multiple files separated by a comma:
  ExampleDrive:\RandomFilePath\JustAnExample\FolderTheFile.xml, ExampleDrive:\RandomFilePath\JustAnExmple\Folder\NotTheFile.xml, ExampleDrive:\RandomFilePath\JustAnExample\Folder\TopSecretFile.xml
  
  
• wildcard:
  ExampleDrive:\RandomFilePath\JustAnExample\*.xml

Notes regarding the above command:

• it can only be used to import custom steps/tasks - not system steps/tasks.
• it uses a wildcard (*.xml) if a folder/directory is given, to ensure that only XML files are used.
• -ignore is an optional parameter that allows steps/tasks to import even if an error is encountered trying to add a step/task. Entuity recommends that you do not use this unless advised by Entuity Support.
• it can be used without the '.exe' extension.
• steps are imported before tasks.
• exported files are in the format given in the Required format of XML files section above.
• a message is given to state when the import started and stopped (assuming it successfully completed and there are no error messages):
  

  C:\entuityImages\trunk\install>cmHelper.exe --export --scope all --path C:\testone
  Importing steps and tasks...
  Finished importing steps and tasks

To export system and custom steps and tasks:

You can export system and custom steps and tasks using the following command in the command line:

%ENTUITY_HOME%\install\cmHelper.exe --export --scope=[custom/system/all] --path=$Path

or

%ENTUITY_HOME%\install\cmHelper.exe --export --scope [custom/system/all] --path $Path

For export commands, the specified file path can be one of the following:

• folder:
  ExampleDrive:\RandomFilePath\JustAnExampleFolder - the folder will be populated with individual XML files defining each step/task.
• file:
  ExampleDrive:\RandomFilePath\JustAnExample\Folder\TheFile.xml - the file will be cleared and populated with individual XML files defining each step/task. If a file by that name does not exist in this directory, then a new XML file will be created.

The following options for $Scope are available:

• -all - this exports all steps and tasks (both system and custom).
• -system - this exports only system steps and tasks.
• -custom - this exports only custom steps and tasks.

Notes regarding the above command:

• it can be used without the '.exe' extension.
• exported files are in the format given in the Required format of XML files section above.
• a message is given to state when the import started and stopped (assuming it successfully completed and there are no error messages):
  

  C:\entuityImages\trunk\install>cmHelper.exe --export --scope all --path C:\testone
  Exporting steps and tasks...
  Finished exporting steps and tasks

To output help for importing and exporting steps and tasks:

You can output help using the following command in the command line:

%ENTUITY_HOME%\install\cmHelper.exe --help

This produces the following output:

C:\entuityImages\trunk\install>cmHelper.exe --help
cmHelper COMMAND HELP:

To import:
cmHelper --import --ignore=[enabled/disabled] --path=$Path
OR
cmHelper --import --ignore [enabled/disabled] --path $Path
To export:
cmHelper --export --scope=[custom/system/all] --path=$Path
OR
cmHelper --export --scope [custom/system/all] --path $Path