Administrator SDK 2.0 Release Notes
|Article:HOWTO9812|||||Created: 2009-02-26|||||Updated: 2012-10-31|||||Article URL http://www.symantec.com/docs/HOWTO9812|
What do I need to know about the 2.0 release of the Administrator's SDK?
Symantec Administrator Software Development Kit (ASDK) Version 2.0 Release Notes
Support for Notification Server 7.0
The Symantec Administrator Software Development Kit (ASDK) version 2.0 has been updated and revised to support new features, constructs and architectural changes in Notification Server 7.0 (NS 7.0).
ASDK 2.0 contains support for NS 7 core functionality and Task Server 7 functionality.
New Features and Modifications
Release 2.0 implements the following new features and modifications:
- A HierarchyManagement library has been added. This library supports operations in the Hierarchy functionality included in Notification Server 7.0 (NS 7). It includes the following APIs:
- CreateCustomEventHierarchyRule – Creates a hierarchy event replication rule with a custom schedule.
- CreateCustomItemHierarchyRule – Creates a hierarchy item replication rule with a custom schedule.
- CreateCustomResourceHierarchyRule – Creates a hierarchy resource replication rule with a custom schedule.
- CreateCustomSecurityHierarchyRule – Creates a hierarchy security replication rule with a custom schedule.
- CreateStandardEventHierarchyRule – Creates a hierarchy event replication rule with a standard schedule.
- CreateStandardItemHierarchyRule – Creates a hierarchy item replication rule with a standard schedule.
- CreateStandardResourceHierarchyRule – Creates a hierarchy resource replication rule with a standard schedule.
- CreateStandardSecurityHierarchyRule – Creates a hierarchy security replication rule with a standard schedule.
- EnableHierarchyEditableProperty – Enables or disables a hierarchy-editable property.
- EnableHierarchyReplication – Enables or disables the local Notification Server’s participation in a hierarchy environment.
- EnableReplicationForItemInstance – Enables or disables replication for the given Item instance.
- GetEnabledHierarchyEditableProperties – Gets the names of the hierarchy-editable properties on the given Item that are currently enabled.
- GetHierarchyEditableProperties – Get the names of the hierarchy-editable properties on the given Item.
- IsHierarchyManaged – Determines whether an Item is hierarchy-managed, i.e., has been replicated from another NS Server as part of hierarchy replication.
- IsHierarchyMember – Determines whether the current Notification Server is a member of a hierarchy.
- IsHierarchyPublished – Determines whether an Item is hierarchy-published, i.e., has been enabled for replication throughout a hierarchy.
- RunCompleteReplication – Run complete replication on the given hierarchy node Item.
- RunDifferentialReplication – Run differential replication on the given hierarchy node Item.
- A ScopingManagement library has been added. This library supports operation related to the NS 7.0 concept of resource scoping. It includes the following APIs (note that APIs that return GUIDs or items return a set scoped for the current user):
- AssignResourcesToOrganizationalGroup – Assigns one or more Resource Items to an organizational group.
- AssignResourceTargetsToPolicy – Associates a set of resource targets to a policy.
- CreateOrganizationalGroup – Creates an organizational group and assigns it to a view.
- CreateOrganizationalView – Creates an organizational view.
- CreateResourceTarget – Creates a resource target.
- DeleteOrganizationalGroup – Deletes an organizational group.
- DeleteOrganizationalView – Deletes an organizational view.
- GetOrganizationalGroupDirectMembership – Returns the GUIDs of all direct members of a given organizational group.
- GetOrganizationalGroupMembership – Returns the GUIDs of all members of a given organizational group, whether direct or indirect.
- GetOrganizationalGroupsFromOrganizationalView – Returns the GUIDs of all organizational groups that are members of a given organization.
- GetOrganizationalViews – Returns the GUIDs of all active organizational views on the system.
- GetOrganizationalViewsFolderGuid – Returns the well-know GUID of the “Organizational Views” folder that is the parent folder to all other organizational views.
- GetResourcesTargetedByPolicy – Returns a list of the GUIDs of the resources that the given policy currently targets.
- GetResourceTargetMembership – Returns a list of the GUIDs of the Resource Items contained in a resource target.
- GetResourceTargets – Returns a list of the GUIDS of the resource targets that currently apply to the given Client Configuration Policy.
- IsInOrganizationalGroup – Determines whether a given Resource Item is a member of a given organizational group, either directly or indirectly.
- IsInOrganizationalGroupDirectMembership – Determines whether a given Resource Item is a direct member of the given organizational group.
- MoveOrganizationalGroupWithinOrganizationalView – Moves an existing organizational group to a different position in the organizational group containing that group.
- RemoveResourcesFromOrganizationalGroup – Removes a given set of Resource Items from the organizational group that contains them.
· The CollectionManagement library has been revised and updated to reflect architectural changes in NS 7.0. In NS 6.x, collections were the container that was targeted for action by, for example, policies and tasks. In NS 7, collections no longer fulfill this role; instead, the new construct "Resource Target" is the target of policies and tasks. The CollectionManagement API set has been modified to reflect this change in role for a "collection." The “collections” for which ASDK 2.0 provides functionality are those collections that have been re-defined in NS 7 for use as “filters” in setting Resource Targets. The NS 6.x collections are no longer supported in NS 7.0 or in ASDK 2.0, except as legacy inputs for Resource Target filters. This means that GUIDs used as inputs to ASDK 1.x CollectionManagement API calls will no longer work. The GUIDs used must now represent NS 7 collection “filters” of type Altiris.NS.StandardItems.Collection.NSDataSrcBasedResourceCollection or Altiris.NS.StandardItems.Collection.NSDataSrcBasedWithExplicitResourceCollection. All your existing scripts or programs that call CollectionManagement APIs in the 1.x ASDK against the NS 6.x should be reviewed and revised accordingly.
· The following APIs have been removed from the ItemManagement library due to architectural and security changes in NS 7.0:
In addition, ItemManagement contains a new API called RunAutomationPolicyTask, which executes a Task Management task linked to an Automation Policy.
· Due to architectural changes involving reports in NS 7.0, the ReportManagement library has a new API called CreateReportUsingRawSqlQuery. This API essentially replaces the now-defunct CreateReport API in ASDK1.x. CreateReportUsingRawSqlQuery allows you to set the data source of an NS 7 report using a raw SQL query. The rest of the ASDK 2.0 API set for ReportManagement remains the same as in ASDK 1.x, except that the APIs (GetReportParameters, RunReport and RunReportWithParameters) will accept report GUIDs for either NS 6.x reports or NS 7 reports.
· In the ResourceManagement library, the ASDK 1.x APIs ComputerPowerManagement, ComputerManagement_Collection and CreateInventoryNSE have been removed in response to architectural changes in NS 7.0. In addition, the library has a new API called CreateResourceAssociation, which was previously located in the AssetManagement module in ASDK 1.x.
· The AssetManagement module found in ASDK 1.x has been removed due to organizational changes in the NS and its solutions. The CreateResourceAssociation previously found in the module is located in the ResourceManagement library in ASDK 2.0.
- The pre-defined “Tasks” that were introduced in ASDK version 1.4 for use in the NS Task Server console have been discontinued. The ASDK 2.0 continues to include the original three interfaces (commonly called "layers") for accessing ASDK functionality: (1) a COM layer, (2) a web service layer, and (3) a Command-Line Interface (CLI) layer.
· ASDK 2.0 contains modules for NS 7 and Task Server 7 only.
Supported Symantec Management Platform Versions
ASDK 2.0 is supported for the following Symantec Management Platform versions:
- Notification Server: 7.0.3876 or later.
- Task Server: 7.0.2904 or later.
- The ItemManagementLib library: Schedules for certain policies such as advertisements
- The ItemManagementLib library interacts with item schedules in various ways. For example:
- Several ItemManagementLib methods return an ItemDetails object (or an array of such objects) that contains the properties "IsSchedulableItem" and "ScheduleXml." These properties contain a boolean value indicating whether the item is schedulable, and an XML string containing the current schedule for items that are schedulable, respectively.
- The SetItemsSchedule() method allows the user to set a new schedule for a schedulable item.
- The ExecuteSchedulableItem() method calls the schedule execution method on a schedulable item.
- The key to working with these properties and methods is understanding what a "schedulable item" is within the context of the ItemManagement library. In this context, a schedulable item is any item that supports scheduling of server-side tasks. (Internally, this is implemented by having the item implement the Altiris.NS.ItemManagement.IItem.IItemScheduling interface.) If an item does not implement the IItemScheduling interface, it does not support scheduling of server-side taks and consequently it should not be considered a "schedulable item" for puposes of the ItemManagement module. Please note that this is true even though certain other items, such as an advertisement, support client-side scheduling even though they do not support server-side scheduling using the ItemManagement methods.
- For example, although the user can set a client-side schedule for a software delivery advertisement in the Symantec Management Console, within the scope of the ItemManagement library an advertisement item is not a "schedulable item" because an advertisement item (Altiris.NS.StandardItems.SoftwareDelivery.AdvertisementItem) does not implement IItemScheduling.
- An advertisement item is a specific type of Policy class. The Policy class itself does not implement IItemScheduling; therefore, custom types deriving from Policy may or may not be "schedulable items" depending on whether the given type itself implements IItemScheduling. For example, an AdvertisementItem is not server-side schedulable, but a NotificationPolicy is server-side schedulable.
- If you are unsure whether a certain policy type is schedulabe for purposes of ItemManagement, check the type's interfaces or inheritance using Microsoft Visual Studio's Object Browser or any other disassembler program.
- Using the ItemManagement library to work with the schedule of a policy, such as an advertisement, that does not implement IItemScheduling may cause an exception to be thrown or other unexpected result, such as causing the Symantec Management Console to hang.
- For example, if an AdvertisementItem GUID is passed in as an argument to ItemManagement.GetItemByGuid(), the IsSchedulableItem property in the returned ItemDetails object will contain the value false and the ScheduleXml property will be empty. This is the expected result, since an advertisement supports only client-side scheduling, not server-side scheduling.
- Similarly, an advertisement item cannot be scheduled using the ItemManagementLib.SetItemsSchedule() method, as it will throw an exception.
- The ItemManagementLib library interacts with item schedules in various ways. For example:
To install ASDK 2.0, you must first completely uninstall any current (1.x) version of the ASDK on all machines where it has been installed and then install the version 2.0. Please note that the ASDK supports only the latest released versions of Notification Server and its various solutions (including the latest service pack).
Note that the ASDK 2.0 is comprised of two separate installation pieces: The required “server-side” installation is performed via the Symantec Installation Manager (SIM) tool. Please see the Symantec Management Platform documentation for information on where to download this tool. This installation will download and install the NS and Task modules, as well as a number of coding and scripting samples. It will install the core “integration assemblies” (Altiris.ASDK.NS.dll and Altiris.ASDK.Task.dll) in the Global Assembly Cache (GAC) of your NS server, as well as installing the ASDK’s web services for NS and Task Server. It will also install the CLI executables for NS and Task Server.
The second installation piece is optional but recommended. If you want to install support for the COM layer (so that you can run the ASDK from a VBScript, for example) you will need to download the Symantec_ASDK.exe install from the Symantec download site. Run this executable from each computer where you want to install the COM layer. This can be the NS Server, or any other Windows computer that has the Microsoft .NET Framework v3.5 installed. (NOTE: This install will also give you the option of installing the CLI layer for the Altiris Agent, if the computer has an Altiris Agent installed. The Agent CLI will allow you access the existing Agent’s COM components via the Command Line.)
To install the complete ASDK 2.0, complete the following steps:
Part I – Uninstall ASDK version 1.x
- Click Start > Control Panel > Add or Remove Programs
- In the Add or Remove Programs dialog click on "Altiris ASDK".
- Click the Remove button.
- A dialog will appear warning you that this will remove all the ASDK components on this machine. Click Ok.
- After a few minutes a dialog will appear indicating the ASDK has been uninstalled. Click Ok.
- Be sure to uninstall the ASDK on both the NS Server and on any remote computer on which the Altiris ASDK 1.x COM pieces have been installed.
Part II – Install the Server components
Run the Symantec Installation Manager (SIM) on the Notification Server machine where you want to install the ASDK 2.0.
Make sure you update the SIM to the latest version and it will have an up to date PL (Product Listing) for example: \Program Files\Altiris\Symantec Installation Manager\Installs\Altiris\symantec*.pl.*. This can be modified using the settings button in the upper right of the Symantec Installation Manager.
Select the "Symantec Administrator SDK" product and proceed with the installation. If "Symantec Administrator SDK" is not visible in the product list, make sure no filters are selected and that the PL is one that references the Administrator SDK.
Part III – Install the COM components
Article URL http://www.symantec.com/docs/HOWTO9812