How to use the Import/Export Utility for NS

book

Article ID: 179721

calendar_today

Updated On:

Products

Patch Management Solution for Windows Management Platform (Formerly known as Notification Server)

Issue/Introduction

 

Resolution

Question
How do I use the Import/Export Utility for NS?

Answer

Where is the ImportExportUtil.exe located?

By default, there are two versions of the Import/Export utility that are installed on a Notification Server 6.

The first version, build 6.0.6074.0 is installed in the "Program Files\Altiris\Notification Server\bin" directory.

The second version, build 6.1.7631.0 is installed in the "Program Files\Altiris\Diagnostics" directory. 
 
For Symantec Management Platform 7.0 (NS7), it should be located under ...\Program Files\Altiris\Notification Server\Bin\Tools. It should work the same way as it did with Notification Server 6.0. The build version should be 7.0.7416.0
Note: ImportExportUtil.exe was reintroduced until SMP 7.0 SP4, prior to that, it was not part of the available utilities for NS7.

What security context must the Import/Export utility be run in?

When the Import/Export utility runs, it checks the logged on user (the context it is being run in when run interactively unless the Run As right-click option is used and then that identity would be checked) to make sure it is part of the Altiris Administrators group.

When run from an NS policy, it is going to run as the Altiris Application Identity. This account currently is not necessarily a member of the Altiris Administrators local group as it is this service account which runs the Altiris Service. And the Altiris Service is the mechanism through which access is granted or denied. To make sure this functions properly when run through an NS policy the Altiris Application Identity should be added to the Altiris Administrators local group.

If the utility is not run in the proper context it will log the following Information (level 4) message in the NS log: The current user {0.EN_US} is not a member of the Altiris Administrators group

Alternatively, the utility could be scheduled through the standard Windows Scheduled Tasks folder which is found in the Windows Explorer window under My Computer > Control Panel > Scheduled Tasks. When there, select the Add Scheduled Task item and follow the wizard prompts. A command line, identity, and schedule can be set. Make sure the Identity is a member of the Altiris Administrators group.

What are the command line parameters for the Import/Export Utility?

  • Command: /import <path to either item.xml file OR directory>
  • Description: Imports an xml file or a directory into the NS.
  • Example: ImportExportUtil.exe /import "c:\All Computers.xml"
    • Imports just one file
  • Example: ImportExportUtil.exe /import "C:\Program Files\Altiris\Packages\importexport\"
    • Imports all .XML files in the directory .
      • Note: Invalid files will cause the import to fail.
  • Command: /export <Item OR Folder GUID to export> <Path to export destination folder>
  • Description: Exports an item or a folder to a specific destination folder.
  • Example: ImportExportUtil.exe /export {611C59EE-EDB4-4848-B77B-76DFE91ED303} "C:\Program Files\Altiris\Packages\importexport\"
    • Exports the above GUID if it is just a single item. It will create just one file in the folder.
  • Example: ImportExportUtil.exe /export {E4CC2D9E-50FE-4CF3-93F2-002FCB7F1E9F} "C:\Program Files\Altiris\Packages\importexport\"
    • Exports the above GUID if it is a folder. It will create one file for every item in the folder and also one file for the folder itself. Also, folders with this folder will be exported recursively down to the bottom level contained within the folder whose GUID is put on the command line. Each folder under the first will be exported as a files and all items within will also be exported as a file.

Note! If using the /q or quiet mode switch, use it after /import or /export and before any other argument

What are some of known issues and workarounds with the ImportExportUtility?

The Import can take much longer to complete than the export. Creating items is a much slower process than exporting them. Therefore, it will work best to do a one time mass export and synchronization which will take some time and then only export new items. How can this best be done? Incident filed.

Also do the exported items know what their place is in the hierarchy without the folder definition files? Items exported by right-click don't seem to? Maybe this is the difference which I was thinking about instead of the permissions/security issue between the right-click and the Import/Export Util?

May have to make a script to create the batch file and export the items one by one (called by individual GUID) so that whole folders don't have to me imported and exported all the time when changes are done.

What would be a good hierarchy configuration for using the Import/Export utility?

An ideal scenario would be this:

  • Initially all new items are tested on a testing or staging server. Once they are validated a manual script would be run to move the items to the top level production server.
    • This step is done manually so that untested items are not rolled automatically to the production environment like they would be if the script was set to run automatically on a repeating basis.
  • Then on the production server there is a scheduled, repeating action which continually exports new or changed items. This action would usually be a script or batch file which calls the Import/Export utility with the correct parameters.
    • A sample batch file which exports three folders would look like this:
      ImportExportUtil.exe /export {611C59EE-EDB4-4848-B77B-76DFE91ED303} "C:\exportedItems"
      ImportExportUtil.exe /export {BD25AC12-41BD-4821-BEE9-000D1E40D926} "C:\exportedItems"
      ImportExportUtil.exe /export {108A1F58-FABE-41CE-9BB8-003FAF787243} "C:\exportedItems"
      These GUIDs are obtained by right-clicking on the folders to be exported and selecting Properties. On the General tab of the properties, the GUID at the top of the page is the correct one to use.
    • These items are placed in a known location which is the source for a SWD package.
    • The SWD package is used to transport the exported items to the other NS servers. Per normal NS package processes only the changed or new files are transmitted. So the replication can happen very quickly.

What are the specific usage attributes to be aware of with the Import/Export utility?

  • The utility does not shut down automatically. This was done so that if the utility was run from the Run command (with arguments) from the GUI file system (without arguments), it would not close the widow until Enter was pressed. This allows any messages to be viewed. The /q argument when used will shut the app when import/export is done. This additional argument was added after SP2 was released so it will be available only with SP3.
    • The /q switch is necessary to being able to script via batch file the operation of the utility. So get the SP3 version if necessary. It will work with SP2.
    • /q must be the second switch after either the /export or /import switch or the utility will not run in the quiet mode.
  • The utill was created to overcome issues the NS UI had with exporting and importing large amounts of data.

It uses standard NS Item import and export methods and will export/import just as if doing it from the UI but with no data size limitations. It does nothing to alter the items it acts on.

  • The utility may consume large amounts of memory if thousands of Items are exported in the same execution of the utility. If necessary export folders with separate calls by simply calling the utility multiple times in the batch file with different folder GUIDs and the /q switch so that it goes automatically from one export to the next. With then end of each execution it will release the memory it used for that run.
    • Using the utility as it currently functions it will work best if there is an option with creation of the folder structure in NS to put the items to be exported only in folders which have no sub-folders. Then only the folders desired can be exported, and not a recursive inclusion of all sub-folders of the folder being exported.
      • For an initial synchronization, a full recursion is a valuable feature which allows everything to be captured at once. But for incremental syncs after the first it may not be so valuable, especially without a time stamp.
      • The export of only the modified or added items could be accomplished by using an NS policy which uses a query that accesses the ModifiedDate column of the Item table, returns the GUIDs of only those items which have been modified, and then executes the command line (once for each row returned) with ImportExportUtil.exe /export and a %variable% which returns the GUID of the item to be exported. However the import may be an issue if items from various folders are exported at the same time as the association of the item to the folder may be an issue. This issue is taken care as described below by creating separate file system folders under the specified export folder name for each of the console folders exported and having a thisfolder.xml file in each.
      • From page 145 of the NS Reference guide: MaxNPResultRows REG_DWORD Specifies the maximum number of rows returned when using %Results% in the message body of an Email Handler in a Notification Policy. The default is 100 rows. Page 52 and 53 of the NS Help SP2 talks about 'Policy Action Parameters'. This section is in the NS policy directly after the the <scheduling> node. The format can be seen by viewing as XML any predefined NS policies (example: Tasks tab, Tasks folder, Notification Server folder, Alert Manager Notification Policies folder, and High Priority Items Not Assigned within 'N' minutes policy.

Example: <policyActionParameters> <policyActionParameter name="Solution" sourceType="DataSet" sourceField="Name" /> </policyActionParameters>

  • Files to be imported must end with .XML or they will not be imported.
  • Folders to be imported must have a thisfolder.xml file or it will not be imported. If missing the following Error level (level 1) message will be put in the NS server log: Failed to import folder [{0.EN_US}]. The folder must have thisFolder.xml file in it.
  • When folders are exported which contain multiple folders the export to a directory will have directories created with the same names as the folders in the NS console. They will each have a thisfolder.xml file and the items which are contained within those folders will be exported to that folder. This is how the utility maintains the console tree location for the exported items.
  • The order of the argument must be as described in the docs or in the /? help for the utility or it will not function as expected.
  • If the command line path specified plus any additional folders and the name of the file is longer than 260 characters the export will fail.
  • Will throw the following self-explanatory errors on import:
    • Cannot add null item to this folder ({0.EN_US}).
    • Cannot add an item to a folder that the item already belongs to.
    • Cannot add an item from Product {0.EN_US} to a folder that the belongs to another Product {1.EN_US}.

What is the scenario where the Import/Export utility can be of value when used with Patch Management?

The Import/Export utility has a number of usage scenarios. It could be as simple as keeping one directory of packages synchronized between two servers to something as complex as synchronizing packages, programs, advertisements, reports, and policies down the tree of a multiple tier NS hierarchy with hundreds of NS servers. The former would be very simple to implement and the latter would generally require at least a few weeks of work and testing.

  • Patch Management 6.1 does not use fixed package GUIDs. The policies, advertisements, and other resources do have fixed GUIDs but the package GUIDs are generated and assigned by the NS server when the Patch Management packages are enabled. In general this is not an issue as Patch keeps track of all of this as part of its normal processes. However for customers using multiple NS servers served by an enterprise wide ACNS network it is an issue.
    • The ACNS devices have 40–80 GB hard drives, and with the media content they are usually in place to serve, there is usually only a limited amount of space available for NS packages.
    • So caching a copy of each of the Patch packages for each of the different NS servers would not likely be possible because of space issues. Also the increased ACNS management setup and configuration to replicate from each of the NS servers would need to be evaluated.
    • To conserve ACNS space (and also not have redundant copies of each of the packages) and reduce management complexity all of the NS servers can be directed to the packages on one NS server or package server. This is accomplished via scripts and configuration outlined in the ACNS doc which is available in MyAltiris by searching for ACNS at the home page.  The current link is: http://myaltiris/C5/TRC%20Documents/Document%20Library/Notification%20Server%20and%20Solutions/NS%20Core/ACNS.doc (This article has also been attached to this KB.  Access from the right-hand pane)
      • When all computers are pointed to the same source as above then the GUIDs for the packages need to be the same from NS to NS. If they are not then all of the clients reporting to a server other than the first NS server will not find their packages. They will be attempting to download packages which do not exist. To resolve this issue the Import/Export utility should be used to export the packages from the first NS server and import them on all of the other NS servers. This will ensure that the GUIDs for the packages are consistent.

What are the functions/uses of the Import/Export Utility?

The NS console allows items (packages, reports, advertisements, policies, etc) to be exported via a right-click. The Import/Export utility allows the same functions to be executed. Having this as a utility which can be run from the command line allows operations to be scripted and automated via batch files or other methods. Items can be synchronized from one NS server (like a staging or top-level server) to other NS production or child servers.

  • Multiple individual sections can be exported on a schedule and imported by as many other NSs as are necessary. This utility allows a functioning hierarchy to be built. When properly implemented there will be minimal if any administrative interaction necessary for the hierarchy operations.
  • The NS itself can load the exported files as advertisements, packages, and programs using the utility and a script. No external mechanisms are necessary.
  • The Import/Export utility will export single items, folders and their contents of items, or it can recurse folder structures exporting both the folders and their contents.

Attachments

ACNS.doc get_app
ACNS.doc get_app