Patch Management Workflow Web Service Application Programming Interface (API)

search cancel

Patch Management Workflow Web Service Application Programming Interface (API)

book

Article ID: 184972

calendar_today

Updated On:

Products

Patch Management Solution Client Management Suite IT Management Suite

Issue/Introduction

Patch Management Workflow Web Service is installed with Patch Management Solution. The Service contains an API that accesses the functionality of the Notification Server (NS) and lets you perform various patch management actions.

Resolution

The PatchWorkflowSvc Web Service page presents the list of available methods along with method call examples. You can invoke the methods on this page.
You can access the page at http://localhost/Altiris/patchmanagementcore/patchworkflowsvc.asmx
Starting from 8.5 RU3, the HTML Help page is introduced. The page includes a list of available methods, detailed descriptions of methods and their parameters, and usage examples for some methods.
You can access the page at http://localhost/Altiris/patchmanagementcore/patchworkflowsvc.html

The following API methods are added in 8.5 RU3:

CreateWindowsUpdateAssessmentTask
CreateWindowsUpdateInstallationTask
EditWindowsUpdateAssessmentTask
EditWindowsUpdateInstallationTask

The following API methods are deprecated in 8.5 RU3:

IsCleanUpAfterUpgrade71Finished
RunCleanUpAfterUpgrade71

The API is exposed as Web Service (SOAP) and has the meta-information that documents each API method if you open the service URL in a browser and allows you to test it directly from the browser if the service URL is opened there.

Most of the API methods use only primitive data types so there are no restrictions on where to call them from. If API receives a GUID or a list of GUIDs, they are provided as strings. In the case of the GUID list, GUID entries are comma-separated.

If some NS item is loaded during the API call, the item access security applies automatically depending on the caller identity.

Parameters

Name	Description
1. AddGuids	This is generic API to append GUID or list of GUID's to some property of NS item.
2. CreateAgentPluginPolicy	Creates Patch Agent Plugin policy.
3. CreatePatchInstallationTask	[obsolete] Similar to CreateWindowsUpdateInstallationTask
4. CreateUpdatePolicy	Creates a Software Update policy. To set additional policy options see SetProperty
5. CreateUpdatePolicyViaUpdates	Creates a Software Update policy based on list of updates.
6. CreateWindowsUpdateAssessmentTask	Creates a 'Windows Software Update Assessment' task.
7. CreateWindowsUpdateInstallationTask	Creates a 'Windows Software Update Installation' task.
8. DisableBulletins	Disables provided bulletins and removes them from policies (optionally).
9. EditPatchInstallationTask	[obsolete] Similar to EditWindowsUpdateInstallationTask
10. EditWindowsUpdateAssessmentTask	Updates 'Windows Software Update Assessment" task.
11. EditWindowsUpdateInstallationTask	Edits the 'Windows Software Update Installation' task.
12. EnsureStaged	Ensures the list of bulletins (and bulletins updates) is staged.
13. GetAllStagedUpdates	Returns the list of ALL staged updates.
14. GetCustomSeverities	Returns the list of Patch Custom Severities as comma-separated entries: <Order>\|< Name>\|<Level>, …
15. GetCustomSeverityLevels	Gets IDs of custom severities.
16. GetDistributionTaskStatus	Returns current "Distribute Software Updates" task status.
17. GetNonstagedUpdates	Returns the list of non-staged updates for provided bulletins.
18. GetPackageServerGuid	Obtains list of Package Servers and returns GUID of the first non-constrained.
19. GetPreImportStatus	Returns the status of pre-import for particular Patch Meta Data import task.
20. GetPreImportStatusVerbose	Returns the verbose status of pre-import for particular Patch Meta Data import task.
21. GetProperty	Very generic API to get property of any NS item.
22. GetStagedUpdates	Returns list of staged updates for provided bulletins.
23. GetStagingTaskStatus	Returns current status for "Download Software Update Package" task. Same result type as for GetDistributionTaskStatus
24. GetTaskInstanceStatus	Returns current status for any task. Also see GetStagingTaskStatus or GetDistributionTaskStatus
25. GetTaskRunningInstances	Returns the GUID list of all task instances, which are running for particular task.
26. GetWindowsPreImportStatus	Returns the status of pre-import of "Import Patch Data for Windows".
27. GetWindowsPreImportStatusVerbose	Returns the verbose status of pre-import of the "Import Patch Data for Windows" task. Same as GetPreImportStatusVerbose, but no parameters required
28. IsSoftwareUpdateDistributionRunning	Returns status of "Distribute Software Updates" task.
29. IsStaged	Checks if ALL provided bulletins and updates are staged.
30. IsStagingTaskRunning	Checks if 'Download Software Update Package' task is running.
31. IsTaskRunning	Checks if particular NS task has running instances.
32. MyPrivileges	Returns list of all privileges, granted for the current API user.
33. OperatePatchWorker	Manages execution of specified 'Import Patch Data' task for different platforms. For example: it can start or stop the task.
34. ResolveToPolicies	Gets the GUID list of policies, created for listed bulletins or updates.
35. ResolveToUpdates	Gets the GUID list of all updates for provided bulletins.
36. RunPatchWorker	Starts provided 'Import Patch Data for ...' task.
37. RunPreImport	Runs the pre-import for particular Patch Meta Data import task.
38. RunTask	Runs any NS task (with its current settings).
39. RunWindowsPreImport	Runs the pre-import part for Windows Patch Meta Data import task.
40. SetAdvertisementCustomCmdLine	Sets custom command line for SoftwareUpdateAdvertisement.
41. SetGuidCollectionProperty	Generic API to change assigned list of objects to provided property. Another generic method: see SetProperty
42. SetPluginPolicyMessages	Changes the Patch plugin policy messages (defined in the Notification tab of the policy).
43. SetPluginPolicyMicrosoftUpdateOptions	Sets options for provided 'Microsoft Update Configuration' policies.
44. SetPluginPolicySchedules	Changes Patch plug-in policy schedules.
45. SetProperties	Very generic API to change properties of NS items.
46. SetProperty	Very generic API to change one property of NS items. To set list of objects as value see SetGuidCollectionProperty
47. SetSeverityLevel	Changes the bulletin severity.
48. SetSoftwareUpdatePolicySchedule	Changes the Software Update policy scheduling.
49. SetSoftwareUpdatePolicyTargets	Changes the targets for policies.
50. SetupImport	Changes Windows import task settings
51. SetupPreImport	Changes the pre-import settings for Patch Meta Data import task.
52. SetupWindowsPreImport	Sets up pre-import properties of "Import Patch Data for Windows" task
53. StopPatchWorker	Stops execution of provided 'Import Patch Data for ...' task.
54. StopPreImport	Attempts to stop pre-import, if it is running.
55. StopWindowsPreImport	Same as StopPreImport, but does not require parameters.
56. UpdateResourceTargets	Updates all resource targets belonging to particular product.
57. UpdateSoftwareUpdatePolicy	Revises Software Update policies with vendor changes.

Methods

1. AddGuids(System.String,System.String,System.String,System.Boolean)

This is generic API to append GUID or list of GUID's to some property of NS item.

Parameters (in order of usage):

Name	Description
guidItem	GUID of NS item, which we want to modify
name	property name in the NS item to modify
guidList	comma-separated list of GUIDs to add to the property
setback	boolean, set to 'true' if resulting GUID collection should be set back to NS item at once

Return value: 'true' on success, 'false' on fail

2. CreateAgentPluginPolicy(System.String,System.String,System.String,System.String)

Creates Patch Agent Plug-in policy.
Gets the 'Default Software Update Plug-in Policy' item, clones it and sets the new name.

Parameters (in order of usage):

Name	Description
strName	[optional] name of the new policy
productGuid	[not supported] leave empty to use 'Patch Core' product
parentFolderGuid	[optional] GUID of the parent folder of the policy (leave empty to use folder of 'Default Software Update Plug-in Policy')
targetGuids	GUID list of resource targets for a policy. See functions like 'CreateResourceTarget' of platform API (Scoping Management) to manage targets

Return value: GUID of created policy

3. CreatePatchInstallationTask(System.String,System.String,System.Boolean,System.String)

Released in: 8.5 RU2
[obsolete] Similar to CreateWindowsUpdateInstallationTask

Parameters (in order of usage):

Name	Description
taskName	[optional] name of the created task
updateGuids	GUID list of updates to include, GUIDs should be comma-delimited
supressRebootDemand	'true' for "Suppress restart during task execution", 'false' for "Restart if required at the end of task execution"
folderGuid	[optional] parent folder for created task, default is "Tasks > Jobs and Tasks > System Jobs and Tasks > Software > Patch Management"

Return value: GUID of created task

4. CreateUpdatePolicy(System.String,System.String,System.String,System.Boolean)

Creates a Software Update policy. To set additional policy options see SetProperty

Parameters (in order of usage):

Name	Description
name	name of the new policy item
bulletinGuids	GUID list of bulletins to include
targetGuids	[optional] GUID list of the Resource Targets for a policy
enabled	'true' if policy should be enabled

Return value: GUID of the created policy
see also: CreateUpdatePolicyViaUpdates
see also: SetProperty

5. CreateUpdatePolicyViaUpdates(System.String,System.String,System.String,System.Boolean)

Released in: 8.5 RU1
Creates a Software Update policy based on list of updates.
Depending on list of updates - usual or partially staged (if only part of updates from a bulletin selected) policy will be created.

Parameters (in order of usage):

Name	Description
name	name of the new policy item
updateGuids	GUID list of updates to include
targetGuids	[optional] GUID list of the Resource Targets for a policy
enabled	'true' if policy should be enabled

Return value: GUID of the created policy
see also: CreateUpdatePolicy

6. CreateWindowsUpdateAssessmentTask(System.String,System.String,System.String)

Released in: 8.5 RU3
Creates a 'Windows Software Update Assessment' task.

Parameters (in order of usage):

Name	Description
taskName	[optional] name of the created task
updateGuids	GUID list of updates to include
folderGuid	[optional] parent folder for created task, default is "Tasks > Jobs and Tasks > System Jobs and Tasks > Software > Patch Management"

Return value: GUID of the created task
see also: CreateWindowsUpdateInstallationTask
see also: EditWindowsUpdateAssessmentTask

7. CreateWindowsUpdateInstallationTask(System.String,System.String,System.Boolean,System.String)

Released in: 8.5 RU3
Creates a 'Windows Software Update Installation' task.

Parameters (in order of usage):

Name	Description
taskName	[optional] name of the created task
updateGuids	GUID list of updates to include
supressRebootDemand	'true' for "Suppress restart during task execution", 'false' for "Restart if required at the end of task execution"
folderGuid	[optional] parent folder for created task, default is "Tasks > Jobs and Tasks > System Jobs and Tasks > Software > Patch Management"

Return value: GUID of the created task
see also: CreateWindowsUpdateAssessmentTask
see also: EditWindowsUpdateInstallationTask

8. DisableBulletins(System.String,System.Boolean)

Released in: 8.5
Disables provided bulletins and removes them from policies (optionally).

Parameters (in order of usage):

Name	Description
bulletinGuids	GUID list of bulletins
deletePolicies	set 'true' to delete provided bulletins from policies or 'false' to leave the bulletins in policies (in disabled state)

Return value: 'true' on success

9. EditPatchInstallationTask(System.String,System.String,System.String,System.String,System.String)

Released in: 8.5 RU2
[obsolete] Similar to EditWindowsUpdateInstallationTask

Parameters (in order of usage):

Name	Description
guidTask	GUID of a 'Windows Update Installation' task
taskName	[optional] new name for edited task
updateGuids	[optional] GUID list of updates to include, GUIDs should be comma-delimited
supressRebootDemand	[optional] true for "Suppress restart during task execution", false for "Restart if required at the end of task execution"
folderGuid	[optional] new parent folder for task

Return value: GUID of the updated task

10. EditWindowsUpdateAssessmentTask(System.String,System.String,System.String,System.String)

Released in: 8.5 RU3
Updates 'Windows Software Update Assessment" task.

Parameters (in order of usage):

Name	Description
guidTask	GUID of a 'Windows Update Assessment' task
taskName	[optional] new name for edited task
updateGuids	[optional] update GUID(s) as comma-delimited string
folderGuid	[optional] new parent folder for task

Return value: GUID of the updated task
see also: CreateWindowsUpdateAssessmentTask

11. EditWindowsUpdateInstallationTask(System.String,System.String,System.String,System.String,System.String)

Released in: 8.5 RU3
Edits the 'Windows Software Update Installation' task.
No need to supply all parameters (guidTask - mandatory), only one can be changed

Parameters (in order of usage):

Name	Description
guidTask	GUID of a 'Windows Update Installation' task
taskName	[optional] new name for edited task
updateGuids	[optional] update GUID(s) as comma-delimited string
supressRebootDemand	[optional] 'true' for "Suppress restart during task execution" option, 'false' for "Restart if required at the end of task execution"
folderGuid	[optional] new parent folder for task

Return value: GUID of the updated task
see also: CreateWindowsUpdateInstallationTask

12. EnsureStaged(System.String,System.Boolean)

Ensures the list of bulletins (and its updates) is staged.
NB! EnsureStaged does not handle bulletin Enabled/Disabled state!

Parameters (in order of usage):

Name	Description
bulletinGuids	GUID list of bulletins to get staged
sync	'true' to wait until everything is staged. 'false' – to let the staging to run asynchronously

Return value: count of updates to be staged or -1 on error

Example:

'EnsureStaged' is not equal to UI action 'Download packages' performed on the bulletin. While it downloads updates if needed - bulleting is not automatically enabled. So the bulletin state 'Staged' isn't equal to 'Enabled' To receive same result as for 'Download packages' UI action for a disabled bulletin: 1. Call 'EnsureStaged' for the bulletin 2. Call 'SetProperty' with property name: IsDisabledByUser and value: false 3. Call 'SetProperty' with property name: Enabled and value: true

13. GetAllStagedUpdates

Returns the list of ALL staged updates.
NB! Might be very long and not fit into the SOAP string size limitation

Return value: list of comma-delimited GUIDs
see also: GetStagedUpdates

14. GetCustomSeverities

Returns the list of Patch Custom Severities as comma-separated entries: <Order>|< Name>|<Level>, …
Example:

1|My Severity One|602,2|My Severity Two|315

15. GetCustomSeverityLevels

Gets IDs of custom severities.
Return value: comma-separated list of severities' IDs (integer)

16. GetDistributionTaskStatus

Returns current "Distribute Software Updates" task status.

The status (Altiris.TaskManagement.Common.TaskInstanceStatus) can be:

Completed
Failed
NotStarted
Started
StopRequested

Return value: status of first active instance of the task or empty string (with no active instances)
see also: IsSoftwareUpdateDistributionRunning

17. GetNonstagedUpdates(System.String)

Returns the list of non-staged updates for provided bulletins.

Parameters (in order of usage):

Name	Description
bulletinGuids	GUID list of bulletins to be checked

Return value: list of comma-separated update GUIDs or empty string
see also: GetStagedUpdates

18. GetPackageServerGuid

Obtains list of Package Servers and returns GUID of the first non-constrained.

Return value: GUID of the first non-constrained Package Server

19. GetPreImportStatus(System.String)

Returns the status of pre-import for particular Patch Meta Data import task.
Use GUID 'C27DBB50-6DDF-4125-87C1-D8F5B588491D' for 'Import Patch Data for Windows' task. Linux tasks are not supported

Parameters (in order of usage):

Name	Description
guidTask	GUID of the Patch Import task for which to check pre-import status

Return value:

0 running
1 stop requested
2 inactive
-1 unknown

Name	Description
guidTask	GUID of the Patch Import task for which to check pre-import status. See GetPreImportStatus

Name	Description
guidItem	GUID of NS item
name	property to get value for

Name	Description
guidTask	GUID of the task to check status for

Name	Description
guidTask	GUID of the task to list running instances for

Name	Description
bulletinGuids	GUID list of bulletins (and/or updates) to be checked

Name	Description
guidTask	GUID of the task to check status for

Name	Description
workerGuid	GUID of the 'Import Patch Data for ...' task
command	Command to execute: "run", "stop", "status", "progress", "verbose" and "message"
async	Boolean flag to make asynchronous execution.

Name	Description
bulletinGuids	GUID list of bulletins or updates to be checked

Name	Description
workerGuid	GUID of the 'Import Patch Data for ...' task to be run.
async	Boolean flag to make asynchronous execution

Name	Description
guidTask	GUID of import task for which to run pre-import

Name	Description
guidTask	GUID of task to execute
instanceName	String for custom instance name, empty by default

Name	Description
AdvertGuid	GUID of the Advertisement
cmdLine	new command line

Name	Description
itemGuids	GUID list of NS items
name	property name
valueGuids	GUID list of values

Name	Description
policyGuids	List of GUIDs of policies for which to set messages
turnOnNonEmpty	Set to 'true' if provided message should be validated for empty string
msgUpdatePending	[optional] text for Software Update Installation Notification message
msgUpdateProgress	[optional] text for Software Update Installation Progress message
msgRebootPending	[optional] text for Software Update Restart Notification message
msgRebootReminder	[optional] text for Reboot reminder message
msgRebootNotification	[optional] text for user deferral notification

Name	Description
policyGuids	GUIDs of policies to modify
enableConfiguration	'true' to enable control over download and installation of updates by Windows Update Agent, disabling automatic download and installation
enableAutoUpdate	'false' to disallow Windows Update to install updates automatically
enablePeer2Peer	'true' to download updates from local computers only
enablePeer2PeerOverInternet	'true' to download updates over Internet
enableNonOsUpdates	'true' to download and install updates for Microsoft products other than Windows (e.g. Microsoft Office)

Name	Description
policyGuids	List of GUIDs of policies to change
clientSoftwareUpdateSchedule	[optional] XML string with schedule info
notifySchedule	[optional] XML string with schedule info
rebootSchedule	[optional]XML string with schedule info

Name	Description
guidItem	The GUID of NS item, which we want to modify
nameValueList	List of name-value pairs

Name	Description
itemGuids	GUID list of NS items to change
name	Name of the property to change
value	Value to set

Name	Description
itemGuids	GUID list of bulletins to be modified
level	Severity level

Name	Description
policyGuids	GUID list of policies to be modified
installSchedule	NS schedule XML string

Name	Description
policyGuids	GUID list of policies to be modified
targetGuids	GUID list of resource targets to set for a policy

Name	Description
softwareExcludes	GUID list of excluded software releases
localeIncludes	GUID list of locales (languages) to import

Name	Description
guidTask	GUID of the task to modify
strMiniCabDownloadUrl	URL of the pre-import cab file
strUserName	User name to access pre-import cab
strPassword	Password of the user to access pre-import cab

Name	Description
strMiniCabDownloadUrl	URL of the pre-import cab file
strUserName	User name to access pre-import cab
strPassword	Password of the user to access pre-import cab

Name	Description
workerGuid	GUID of running 'Import Patch Data for ...' task

Name	Description
guidTask	GUID of the task for which to stop pre-import (one of the Patch Meta Data import tasks)

Name	Description
guidProduct	GUID of the product

Name	Description
policyGuids	List of the Software Update policy GUIDs
enableNewAdverts	Set to 'true' to automatically enable distribution of newly added software updates

Feedback

thumb_up Yes

thumb_down No