REST API - POST Alert Modify

This operation updates an alert.

Request

Syntax

Send the request using either XML or JSON:

XML

 
POST <webservice>/AlertRule/{alertId}/Action/Modify HTTP/1.1
 Host: <host name>
 Accept: application/xml
 Authtoken: <authentication token>
 Content-type: application/xml
 <modify_alerts.xml>

JSON

 
POST <webservice>/AlertRule/{alertId}/Action/Modify HTTP/1.1
 Host: <host name>
 Accept: application/json
 Authtoken: <authentication token>
 Content-type: application/json
 <modify_alerts.json>

where <webservice> is the root path used to route the API requests to the Web Server.

For more information, see Available Web Services for REST API.

Request Parameters

Name	Description	Required
alertId	The alert ID for the alert. If the alert ID is not known, use the GET Alert API to retrieve it.	Yes

Request Headers

Name	Description
Host	The host name of the Web Server or Web Console used in the API request.
Accept	The format of the response. Valid values are: application/xml or application/json.
Authtoken	The authentication token received after successfully logging on. For details on receiving an authentication token, see Authentication.
Content-type	The media type contained in the request body.

Request Body

Download the XML or JSON file required for this request: modify_alerts.xml or modify_alerts.json. The following table displays the parameters for the request body.

Parameter

Description

Element

Parent Element

entityListOperationType

The operation to perform on the entities associated with the alert. The entities are defined in the elements under the <CVGui_CommCellTreeNode> element.

Valid values:

2, to add values
3, to delete values
any other value, to overwrite values

alertDetail

notifTypeListOperationType

The operation to perform on the notification types associated with the alert. The notification types are defined in the val parameter of the <notifType> element.

Valid values:

2, to add values
3, to delete values
any other value, to overwrite values

alertDetail

alertSeverity

The alert severity.

Valid values are:

0, for Auto Pick
1, for Critical
2, for Warning
3, for Information

alertDetail

senderDisplayName

The display name of the sender of the alert.

alertDetail

senderEmailId

The email address of the sender of the alert.

alertDetail

alertType

The alert type.

Valid values are:

1, for Data Aging
2, for Auxiliary Copy
3, for Data Protection
4, for Data Recovery
5, for Disaster Recovery Backup
6, for Data Verification
7, for Media Inventory
8, for scheduled export
9, for Media Erase
10, for Client
11, for agents
1. for CommCell
13, for MediaAgents
14, for Schedules
15, for Storage Policy
16, for Library
17, for Library Management
18, for VaultTracker
19, for Download Software
20, for Install Updates
21, for Device Status
22, for Erase Data

23, for application exchange
24, for Updates Available for Download
25, for File Replication
26, for Upgrades and Service Packs
27, for Data Classification
28, for Continuous Data Replication
29, for offline content indexing
30, for SharePoint
52, for Report
53, for Information Management
54, for Media Refreshing
55, for DeDup DB Reconstruction
57, for Log Monitoring
58, for Event Viewer Events
59, for Client Group
60, for License
61, for Backup Copy Workflow
62, for log monitoring for Windows events
63, for Workflow
64, for Virtualize Me
65, for custom queries
When the alertCatagory element id parameter equals 9, the alertType element id parameter equals the query ID.

alertDetail

_type_

The type of entity to associate with the alert. Use the _type_ parameter to associate a group of entities or individual entities. For example, <associations _type_="27"/> associates all client groups with the alert. <associations _type_="3" clientId="2" clientName="client001"/> associates a specific client with the alert. To add more than one association, open the .xml file and add the <associations> element for each association, for example:

<associations _type_="27"/>
<associations _type_="3" clientId="2" clientName="client001"/>

To associate all entities of a specific type, the valid values are:

2, for all clients
27, for all client groups
10, for all MediaAgents
8, for all libraries
95, for all log monitoring criteria
16, for all storage policies
20, for all Vault Tracker policies
22, for all Vault Tracker jobs
114, for all workflows

To associate individual entities, the valid values are:
4, for an application type
6, for a backup set
3, for a client
28, for a client group
1, for a CommCell entity
11, for a specific MediaAgent
9, for library
96, for a log monitoring criterion
17, for a storage policy
7, for a subclient
21, for a Vault Tracker policy
83, for a workflow

associations

CVGui_CommCellTreeNode

ID of the entity

The system-generated ID of the entity in the _type_ parameter in the <associations> element.

For example, if _type_="3", then the clientId parameter is included in the <associations> element: <associations _type_="3" clientId="2" clientName="client001"/>.

associations

CVGui_CommCellTreeNode

Name of the entity

The name of the entity in the _type_ parameter in the <associations> element.

For example, if _type_="3", then the clientName parameter is included in the <associations> element: <associations _type_="3" clientId="2" clientName="client001"/>.

associations

CVGui_CommCellTreeNode

exclude

The option to exclude the entity defined in the <associations> element. In the following example, all clients except client001 are associated with the alert:

<associations _type_="2"/>
<associations _type_="3" clientId="2" clientName="client001">
  <flags exclude="1"/>
</associations>

Valid value is 1. If there are no entities to exclude, remove the <flag> element from the XML.

flags

associations

alertName

The name of the alert.

alertrule

alertDetail

alertId

The system-generated ID assigned to the alert.

alertrule

alertDetail

val

The notification type for the alert. To add more than one notification type, open the .xml file and add the <notifType> element for each notification type, for example:

Valid values are:

1, for email
4, for SNMP
8, for event viewer
16, for run command notification type
8192, for console alerts
32768, for SCOM
2097152, for webhooks

notifType

alertDetail

cmdPath

The file path to the command processor executable file.

runCommand (optional)

alertDetail

arguments

The argument values.

Add quotation marks around each value to resolve potential white space issues, for example: "<DETECTED CRITERIA>"

See Available Alert Tokens for a list of tokens or arguments.

runCommand (optional)

alertDetail

userName

The userName of the user who has permissions to modify the alert.

credentials

runCommand (optional)

password

The password of the user who has permissions to modify the alert.

credentials

runCommand (optional)

domainName

The domain name of the user who has permissions to modify the alert.

credentials

runCommand (optional)

userListOperationType

The operation to perform on the users who receive the alert notification.

Valid values:

2, to add users
3, to delete users
any other value, to overwrite users

userList

alertDetail

_type_

Valid value is 13.

userList

userName

The name of the user who receives the alert notification.

userList

userId

The system-generated ID assigned to the user.

userList

userGroupListOperationType

The operation to perform on the user groups that receive the alert notification.

Valid values:

2, to add user groups
3, to delete user groups
any other value, to overwrite user groups

userGroupList

alertDetail

_type_

Valid value is 15.

userGroupList

userGroupName

The name of the user group that receives the alert notification.

userGroupList

userGroupId

The system-generated ID assigned to the user group.

userGroupList

nonGalaxyUserOperationType

The operation to perform on the users who receive the alert notification. These users do not have user IDs in the CommServe database.

Valid values:

2, to add user email addresses
3, to delete user email addresses
any other value, to overwrite user email addresses

regNonGalaxyUserList

alertDetail

val

The email address of the user. This user does not have a user ID in the CommServe database.

nonGalaxyUserList

regNonGalaxyUserList

val

The email address of the user who receives email notifications when the alert is escalated. This user does not have a user ID in the CommServe database.

nonGalaxyUserList

EscNonGalaxyUserList

nonGalaxyUserOperationType

The operation to perform on the users who receive the alert notification. These user email addresses are the Cc or Bcc recipients. These users do not have user IDs in the CommServe database.

Valid values:

2, to add user email addresses
3, to delete user email addresses
any other value, to overwrite user email addresses

nonGalaxyList

alertDetail

nonGalaxyUser

The email address of the user. This user email address is the Cc or Bcc recipient. This user does not have a user ID in the CommServe database.

nonGalaxyUserList

nonGalaxyList

escalationLevel

The option to indicate if the Cc or Bcc user email addresses are added to the regular alert notification or the escalated alert notification. These users do not have user IDs in the CommServe database.

Valid values are:

0, to add user email addresses as the Cc or Bcc recipient for regular notifications
1, to add user email addresses as the Cc or Bcc recipient for alerts that are escalated

nonGalaxyUserList

nonGalaxyList

recipientType

The option to add the user email address as the Cc or Bcc recipient. These users do not have user IDs in the CommServe database.

Valid values are:

1, to add the user email address as the Cc recipient
2, to add the user email address as the Bcc recipient

nonGalaxyUserList

nonGalaxyList

appTypeFilterOperationType

This parameter is available for alert types that can be associated with agents. The operation to perform on the agent filters.

Valid values are:

2, to add values
3, to delete values
any other value, to overwrite values

appTypeFilterList

alertDetail

_type_

Valid value is 79 when the applicationId parameter is used, for example:

<appTypeFilter _type_ ="79" applicationId ="53"/>

appTypeFilter

appTypeFilterList

applicationId

This parameter is available for alert types that can be associated with agents. Filters the entities in the <associations> element.

Valid values are:

53, for Exchange Database
33, for File System
104, for MySQL
13, for NAS
59, for Notes Database
22, for Oracle
80, for Oracle RAC

125, for PostgreSQL
79, for SAP for MAX DB
61, for SAP for Oracle
81, for SQL Server
5, for Sybase Database
29, UNIX File System
106, Virtual Server

appTypeFilter

appTypeFilterList

_type_

Valid value is 78 when the appGroupId parameter is used, for example:

<appTypeFilter _type_ ="78" appGroupId ="1"/>

appTypeFilter

appTypeFilterList

appGroupId

This parameter is available for alert types that can be associated with agents. Filters the entities in the <associations> element. Some agent types in the appGroupId parameter represent a group of agents. For example, <appTypeFilter appGroupId="1"/> is the Files/Protected Files group, and it includes several agents. To select individual Files/Protected Files agents, use the applicationId attribute.

Valid values are:

Database

11, DB2
14, Exchange DB
111, Informix
12, Lotus Notes DB
104, Lotus Notes DB (Transaction Log Subclients)
100, MySQL
10, Oracle
114, PostgreSQL
101, SAP for Oracle
90, SQL Server
13, Sybase

Documentum
115, Documentum

Exchange Mail

7, Archived Mail
8, Journaled Mail
6, Protected Mail

Files
5, Archived Files
1, Protected Files

Lotus Notes
67, Domino Mailbox Archiver
68, Lotus Notes Document

SharePoint
2, Archived Documents
3, Protected Documents

appTypeFilter

appTypeFilterList

criteria

The alert criteria.

Valid values are:

1, for Job Succeeded
2, for Alert every n attempts (Phase failures)
3, for Job Failed
4, for Job Skipped
5, for Delayed by n Hrs
7, for Job Initiated
8, for Rolled Back
10, for Media Handling Required
11, for Media Picked Up
12, for Media Reached Destination
13, for Media Returned to Source
14, for Job Activity
16, for Properties Modified
17, for Alert Modified
18, for Disk Space Low
19, for Force De-configured
20, for Library went Offline
21, for Scheduler Changes
22, for Insufficient Storage
26, for Maintenance Required
27, for Maintenance Occurred
28, for User Overwrite of Media
29, for Drive went Offline
30, for MediaAgent went offline
31, for Mount Path went Offline

32, for Alert every n attempts (Network failures)
38, for Updates Available to Download
39, for Release Upgrade Required
46, for No Data Protection
47, for Classification Failed
51, for Media Recalled
52, for Increase in Data size by n %
53, for Decrease in Data size by n %
54, for Job Started
55, for Alert every n failed login attempts
56, for Auxiliary Copy fallen behind alert
57, for Job Succeeded with Errors
58, for Alert CommServe License Expires Within n Days
60, for Alert when License Consumed reaches n Percent
63, for Non-encrypted media exported
65, for No Backup for last n Days
66, for Alert when client certificate Expires Within n Days
67, for Job exceeded running time of n Hrs
68, for Number of failed files is more than n
69, for Percentage of failed files is more than n
70, for DDB Store got corrupted
71, for Backup for subclient failed consecutively for n attempts
72, for DDB disk space low
73, for Alert when jobs in pending state exceed n percent or count of n
74, for Data backed up exceeds n GB

criteria

alertDetail

localeID

locale

alertDetail

persistTimeSeconds

regularOption

alertDetail

delayTimeSeconds

regularOption

alertDetail

reportingOptions

The option to set notification criteria.

Valid values are:

257, to notify if a condition persists
3, to repeat the notification
5, to notify when the condition clears
259, to notify if a condition persists and to repeat the notification
261, to notify if a condition persists and to notify when the condition clears
7, to repeat the notification and to notify when the condition clears
263, to notify if a condition persists, to repeat the notification, and to notify when the condition clears

regularOption

alertDetail

escalationSeverity

alertDetail

Response

Response Parameters

Parameter	Description	Element
errorCode	The possible error codes. Valid values are: 0, successful completion. 2, a failure. a specific error code.	CVGui_GenericResp
errorMessage	The description of the error code. Not all error codes have an error message.	CVGui_GenericResp

Parameter

Description

Element

errorCode

The possible error codes.

Valid values are:

0, successful completion.
2, a failure.
a specific error code.

CVGui_GenericResp

errorMessage

The description of the error code. Not all error codes have an error message.

CVGui_GenericResp

Examples

Sample Request

POST <webservice>/AlertRule/77/Action/Modify HTTP/1.1
 Host: client.mydomain.com
 Accept: application/xml
 Authtoken: QSDK 38568012f4d1e8ee1841d283a47aa3ba78e124ea58354b5fc6
 0f4dab8a63347d05cf5552484dafda3bfa4c5db84e580b1cb37bcf8e65b39f7f
 8549a443e6f78a2c7be3f31b3d845e24776c835e498e8e883bb40c46bd15af4f
 40ca94e823acedcdd4e9659e74b34a07a85c4586cd2ed914b6dce015874783ef7
 68fda78183a4208930954a377f66eb56c8b92cexampl4s437a19317ca6ce7f323
 3d5a01aca35dbad93468b833f2cf71010809006a937670adce711ca8be46638e8
 Content-type: application/xml
 <CVGui_AlertRuleModifyReq>
   <alertDetail>
     <alertDetail alertType="3" senderDisplayName="John Doe" senderEmailId="jdoe@example.com" alertSeverity="0" notifTypeListOperationType="0" entityListOperationType ="0" >
       <EntityList>
         <CVGui_CommCellTreeNode>
           <associations _type_="2" />
         </CVGui_CommCellTreeNode>
       </EntityList>
       <alertrule alertId="77" alertName="Library Management All" />
       <notifType val="1" />
       <userList userListOperationType ="0">
         <userList _type_="" userId="" userName="" />
       </userList>
       <userGroupList userGroupListOperationType ="0" >
         <userGroupList _type_="" userGroupId="" userGroupName="" />
       </userGroupList>
       <regNonGalaxyUserList nonGalaxyUserOperationType="2">
         <nonGalaxyUserList val="jdoe@mycompany.com" />
       </regNonGalaxyUserList>
       <EscNonGalaxyUserList>
         <nonGalaxyUserList val="jdoe@mycompany.com" />
       </EscNonGalaxyUserList>
       <criteria criteria="22" />
       <locale localeID="0" />
     </alertDetail>
     <regularOption reportingOptions="1" delayTimeSeconds="0" persistTimeSeconds="0" />
     <escalationSeverity escalationSeverity="0" />
   </alertDetail>
 </CVGui_AlertRuleModifyReq>

Sample Response

This is the response when the alert is successfully updated.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?><CVGui_GenericResp errorCode="0" errorMessage="AlertRule modified successfully" />

These are the possible responses when the alert ID in the request is not valid.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 <CVGui_GenericResp errorMessage="Invalid Rule Id [7s]" errorCode="1" />

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 <CVGui_GenericResp errorCode="720899" errorMessage="Alert notification not found" />

This is the response when a user does not have the alert management capability.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?><CVGui_GenericResp errorCode="1" errorMessage="Permission denied : User doesn't have enough permission to edit this alert."/>