REST API - POST Alert

Updated

This operation creates an alert.

Request

Syntax

Send the request using either XML or JSON:

  • XML

    POST <webservice>/AlertRule HTTP/1.1 Host: <host name> Accept: application/xml Authtoken: <authentication token> Content-type: application/xml <create_alerts.xml>

  • JSON

    POST <webservice>/AlertRule HTTP/1.1 Host: <host name> Accept: application/json Authtoken: <authentication token> Content-type: application/json <create_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 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: create_alerts.xml or create_alerts.json. The following table displays the parameters for the request body.

Parameter

Description

Element

Parent Element

alertSeverity

The alert severity.

Valid values are:

  • 0, for Auto Pick

  • 1, for Critical

  • 2, for Warning

  • 3, for Information

alertDetail

CVGui_AlertRuleCreateReq

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

  • 12, 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 offine 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 elementid parameter equals the query ID.

alertDetail

CVGui_AlertRuleCreateReq

senderDisplayName

The display name of the sender of the alert.

alertDetail

CVGui_AlertRuleCreateReq

senderEmailId

The email address of the sender of the alert.

alertDetail

CVGui_AlertRuleCreateReq

_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 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

_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:

  • 41, Active Directory

  • 21, AIX File System

  • 64, Big Data Apps

  • 134, Cloud Apps

  • 37, DB2

  • 103, DB2 MultiNode

  • 62, DB2 on Unix

  • 128, Documentum

  • 90, Domino Mailbox Archiver

  • 91, DPM

  • 67, Exchange Compliance Archiver

  • 53, Exchange Database

  • 45, Exchange Mailbox

  • 54, Exchange Mailbox (Classic)

  • 56, Exchange Mailbox Archiver

  • 82, Exchange PF Archiver

  • 35, Exchange Public Folder

  • 73, File Share Archiver

  • 33, File System

  • 74, FreeBSD

  • 71, GroupWise DB

  • 17, HP-UX Files System

  • 65, Image Level

  • 75, Image Level On Unix

  • 76, Image Level ProxyHost

  • 87, Image Level ProxyHost on Unix

  • 3, Informix Database

  • 29, Linux File System

  • 89, MS SharePoint Archiver

  • 104, MySQL

  • 13, NAS

  • 83, Netware File Archiver

  • 12, Netware File System

  • 10, Novell Directory Services

  • 124, Object Link

  • 131, Object Store

  • 86, OES File System on Linux

  • 22, Oracle

  • 80, Oracle RAC

  • 130, Other External Agent

  • 125, PostgreSQL

  • 38, Proxy Client File System

  • 87, ProxyHost on Unix

  • 61, SAP for Oracle

  • 135, SAP HANA

  • 78, SharePoint Server

  • 20, Solaris 64bit File System

  • 19, Solaris File System

  • 81, SQL Server

  • 5, Sybase Database

  • 66, Unix File Archiver

  • 36, Unix Tru64 64-bit File System

  • 106, Virtual Server

  • 58, Windows File Archiver

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

unit

The measurement unit of the alert criteria.

  • 3, Alert every n attempts (Phase failures)

  • 3, Alert every n attempts (Network failures)

  • 3, Alert every n failed login attempts

  • 3, Backup for subclient failed consecutively for n attempts

  • 3, Data backed up exceeds n GB

  • 5, Delayed by n hours

  • 5, No Backup for last n Days

  • 5, Alert when client is offline for n Minutes

  • 2, Increase in Data size by n%

  • 2, Decrease in Data size by n%

paramsList

criteria

type

The data type of the alert criteria, which is always the integer data type. The valid value is 1.

paramsList

criteria

value

The value of n in the alert criteria.

paramsList

criteria

paramIndex

The index or location of the value parameter. The value is 0.

paramsList

criteria

localeID

The destination of the alert notification.

locale

alertDetail

val

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

<notifType val="4"/>
<notifType val="8192"/>
    

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)

_type_

Valid value is 15.

userGroupList

userGroupList

userGroupName

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

userGroupList

alertDetail

userGroupId

The system-generated ID assigned to the user group.

userGroupList

userGroupList

_type_

Valid value is 13.

userList

userList

userName

The name of the user who receives the alert notification.

userList

userList

userId

The system-generated ID assigned to the user.

userList

userList

val

The email address of the user who receives the alert notification. 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

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

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

The severity of the alert. Valid values are:

  • 1, for a regular alert

  • 2, for an escalated alert

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

Examples

Sample Request

POST <webservice>/AlertRule HTTP/1.1
Host: client.mydomain.com
Accept: application/xml
Authtoken: QSDK 38568012f4d1e8ee1841d283a47aa3ba78e124ea58354b5fc6
0f4dab8a63347d05cf5552484dafda3bfa4c5db84e580b1cb37bcf8e65b39f7f
8549a443e6f78a2c7be3f31b3d845e24776c835e498e8e883bb40c46bd15af4f
40ca94e823acedcdd4e9659e74b34a07a85c4586cd2ed914b6dce015874783ef7
68fda78183a4208930954a377f66eb56c8b92cexampl4s437a19317ca6ce7f323
3d5a01aca35dbad93468b833f2cf71010809006a937670adce711ca8be46638e8
Content-type: application/xml
<CVGui_AlertRuleCreateReq>
 <alertDetail alertSeverity="0" alertType="10" senderDisplayName="John Doe" senderEmailId="jdoe@example.com" notifTypeListOperationType="0">
  <EntityList associationsOperationType="0"> 
     <associations _type_="28" clientGroupId="3" clientGroupName="basic"/>
  </EntityList>
  <EscUserGroupList userGroupListOperationType="0"/>
  <EscUserList userListOperationType="0"/>
  <EscnonGalaxyUserList nonGalaxyUserOperationType="0"/>
  <alertrule _type_="64" alertId="" alertName="failed attempts alert"/>
  <criteria criteria="2"/>
  <locale localeID="0"/>
  <nonGalaxyUserList nonGalaxyUserOperationType="0"/>
  <notifType val="1"/>
  <notifType val="8192"/>
  <userGroupList userGroupListOperationType="0">
    <userGroupList _type_="15" userGroupId="1" userGroupName="master"/>
  </userGroupList>
  <userList userListOperationType="0">
    <userList _type_="13" userId="3" userName="jdoe"/>
  </userList>
 </alertDetail>
</CVGui_AlertRuleCreateReq>
    

Sample Response

This is the response when the alert is created.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 <CVGui_AlertCreateResp alertId="49"/>
    

This is the response when the alert is not created.

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
 <CVGui_GenericResp errorCode="720902" errorMessage="Error controlling alert system for CommCell."/>