The alerts Service
The rest_v2/alerts service provides the interface to create, read, update, delete, and manage single or multiple alerts in the report. When a user schedules an alert in the report to run at a given time, with a given recurrence, the server stores this information in an alert. There can be any number of alerts for any number of reports, all created by different users.
With the server's user interface, the alerts service only manages alerts for the reports that are currently active. Alerts are never listed or returned for the chart reports and the reports without numeric values.
Within the alert, a trigger is said to fire when the specified condition is met. When the condition is met, the server generates the output of the scheduled alert.
For example, consider that you are working in a warehouse. You have to restock the inventory based on the storage space. A report is generated which shows the inventory for the products. You need to check the stock twice a day to maintain inventory value. You can define an alert to notify whenever a stock is low in number. Based on which, a report in the output formats like PDF, Excel is emailed to the recipient as a repository links or attachments.
This chapter includes the following sections:
• | Searching for an Alert |
• | Viewing an Alert Definition |
• | The alert Descriptor |
Searching for an Alert
The GET method of the alerts service has multiple arguments to search for alerts in several ways. The credentials used for authentication determine the scope of the search. Typical users can search only the alerts that they have created. An organization admin (jasperadmin) can search all alerts in their organization, and the system admin (superuser) can search all alerts on the server. This method only returns active alerts, that still have a pending trigger or are still running after their last trigger.
When used without any arguments, this method returns all scheduled alerts defined by the user in the report. The various arguments in this method help you to find an alert created by the user using administrator credentials.
You can perform a string search in the search criteria to find an alert by name in the user interface. The search criteria show results only for those alert whose name matches with the alert name column. You can also control the number of alert results to be displayed in a single alert page using the pagination and sorting order option.
Method |
URL |
||
---|---|---|---|
GET |
http://<host>:<port>/jasperserver[-pro]/rest_v2/alerts?<arguments> |
||
Argument |
Type/Value |
Description |
|
id? |
Integer |
The unique identifier assigned to the alert. |
|
resourceURI? |
/path/to/report |
The URI (repository path) of a report to schedule an alert. Performs a case-insensitive string search for this value anywhere within the resourceURI property of every alert. |
|
owner? |
String |
The name of the user who scheduled the alert. |
|
label? |
String |
The label to search an alert by Alert name. Performs a case-insensitive string search for this value, which contains the label property of every alert. |
|
description? |
String |
The description of the alert. |
|
resourceLabel? |
String |
The name of the report to find alerts in the report. |
|
state? |
String |
The alert states - NORMAL, EXECUTING, COMPLETE, PAUSED, ERROR, UNKNOWN. |
|
previousFireTime? |
String |
The alerts previous fire time. |
|
nextFireTime? |
String |
The alerts next fire time. |
|
example? |
JSON alertModel |
Searches for an alert that matches with the JSON You can search for any parameter in the alert descriptor such as - id, version, trigger, output format, or recipient email. |
|
offset? |
Integer |
Specifies the index of the first |
|
limit? |
Integer |
Specifies the number of |
|
sortType? |
|
Possible values are: |
|
isAscending? |
true|false |
Determines the sort order: ascending if true, descending if false or omitted. This argument is ignored when sortType is not specified. |
|
Options |
|||
accept: application/json |
|||
Return Value on Success |
Typical Return Values on Failure |
||
200 OK - The body contains an array or list of alertsummary descriptors that match the search criteria, as shown in the examples below. |
204 No Content - When no matching alert is found in the server. After an alert finishes running its last triggered instance, it no longer shows up in search results. |
For example, if you want to request all the alerts for a report, then use the following GET method URL (%2F is the / character) in the request:
GET http://example.com:8090/jasperserver-pro/rest_v2/alerts?reportUnitURI=%2Freports%2FAllAccounts
In the response from the server, the alerts are described in an alertsummary
element, such as the following example. The alertsummary
contains a small subset of the properties of the alert descriptor as well as the complete state descriptor:
{ "alertsummary": [ { "id": 4164, "version": 1, "label": "Test", "reportUnitURI": "/public/Samples/Reports/RevenueDetailReport", "reportLabel": "07. Revenue Detail Report", "state": { "previousFireTime": "2023-04-24T15:26:00-07:00", "nextFireTime": "2023-04-26T15:26:00-07:00", "value": "NORMAL" }, "hasDataPointAlert": true, "owner": "superuser", "lastAlerted" : null } ] }
The example parameter lets you specify a search of any property in the alert descriptor, such as output formats. You can specify any property in the alert descriptor or in any of its nested structures. Some properties may be specified in both the example
parameter and in a dedicated parameter, for example label. In that case, the search specified in the example parameter takes precedence.
For example, you can search for all alerts that specify an output format of PDF and XLS. The JSON alertModel to specify this property is:
"outputFormats": { "outputFormat": ["PDF", "XLS"] }
Below is the corresponding URI with proper encoding is:
http://<host>:<port>/jasperserver[-pro]/rest_v2/alerts?example=%7b%22outputFormat%22%3a%22PDF%22%7d
Viewing an Alert Definition
Use the GET method to retrieve details of an alert using its unique id. You can use this method to view an alert definition after searching and finding the ID of an alert that is still active.
Method |
URL |
||
---|---|---|---|
GET |
http://<host>:<port>/jasperserver[-pro]/rest_v2/alerts/{alertId} |
||
Options |
|||
accept: application/alert+json |
|||
Return Value on Success |
Typical Return Values on Failure |
||
200 OK - The body contains a descriptor with all details about the alert. |
404 Not Found - When the specified alert is not found in the server. After an alert finishes running its last triggered instance, it is no longer active, then its ID will return this error. |
The GET method returns a descriptor that includes the various parameters of a scheduled alert. All properties are included, many of which may be null, if not set for the chosen alert. For more information, see The alert Descriptor.
{ "id": 4198, "version": 1, "username": "superuser", "label": "TestPostMan", "creationDate": "2023-04-28T00:46:17.945-07:00", "trigger": { "simpleTrigger": { "id": 4195, "version": 0, "timezone": "America/Los_Angeles", "startType": 1, "misfireInstruction": 0, "occurrenceCount": -1, "recurrenceInterval": 2, "recurrenceIntervalUnit": "DAY" } }, "lastError": null, "baseOutputFilename": "RevenueDetailReport", "exportType": "DEFAULT", "outputLocale": "en_US", "outputTimeZone": "Asia/Calcutta", "source": { "reportUnitURI": "/public/Samples/Reports/RevenueDetailReport", "parameters": { "parameterValues": { "ProductFamily": [ "Drink", "Food", "Non-Consumable" ] } } }, "outputFormats": { "outputFormat": [ "PDF" ] }, "repositoryDestination": { "folderURI": "/public/Test", "id": 4196, "overwriteFiles": true, "sequentialFilenames": false, "version": 1, "saveToRepository": true, "usingDefaultReportOutputFolderURI": false, "outputFTPInfo": { "userName": "anonymous", "type": "ftp", "port": 21, "implicit": true, "pbsz": 0, "propertiesMap": {} } }, "mailNotification": { "bccAddresses": { "address": [] }, "ccAddresses": { "address": [] }, "toAddresses": { "address": [ "xyz@tibco.com" ] }, "version": 1, "id": 4197, "includingStackTraceWhenJobFails": false, "messageText": "test", "resultSendType": "SEND", "skipEmptyReports": false, "skipNotificationWhenJobFails": false, "subject": "test" }, "dataPointAlert": { "id": 4199, "version": 0, "name": "Test API PostMan", "dataPoint": "{\"elementUUID\":\"72a3ea24-62a2-4f04-a5a6-d501046ddbcc\"}", "operator": "EQUALS", "thresholdValue": "0", "dataPointType": "NUMERIC", "resourceURI": "/public/Samples/Reports/RevenueDetailReport" } }
The alert Descriptor
The alert descriptor is a complex data object with nested containers for the various properties that defines a scheduled alert. The alert
descriptor is the output of the GET method with slightly different content, and the input of the PUT and POST methods.
The properties of the alert
descriptor are defined in the following sections:
• | General Properties of an Alert, such as label and description, but also the output format and base filename. |
• | Source and Input Controls includes the repository URL of the report or report option and the parameter value of any input control if any of them are present and applied to the same report. |
• | Simple Trigger defines interval-based repetition of the alert for a given number of occurrences. |
• | Calendar Trigger runs at specific times, specific days of the week or days of the month. |
• | Alert Output Properties define the file name and locations where output files are written. |
• | FTP Output defines whether the output files are written to a remote server. |
• | Alert Output Email defines the recipients for successful output files. |
• | Alert DataPoint defines the numeric values for which an alert is created. |
When submitting an alert descriptor to create or modify an alert schedule, not all properties are needed. In the following tables, each property is one of the following:
• | Required - This property must have a value for input to define a valid alert. |
• | Optional - This property may be omitted on input, either because it is nullable, or because the server assigns a default value. The behavior is explained in the property description. |
• | Conditional - The property may be required or optional depending on other property values. The behavior is explained in the property description. |
• | Ignored - This property is for internal usage or output only, and the server ignores any value on input. Good practice is to omit these properties from your input. |
General Properties of an Alert
A valid alert descriptor contains the following properties:
Property (as input) | Description |
---|---|
|
The ID of the alert assigned by the server. Use this ID to modify, delete, or view the alert. |
|
An internal version number, which is used for optimistic locking of an alert object. |
|
The owner and creator of this alert, including the organization name. Note that only administrators can view other users' alerts. |
|
A name for the alert, like the label of a resource in the repository. |
|
A description string for the alert, which often describes the trigger and chosen output. |
|
The time and date when the alert was first created and managed internally by the server. |
|
A container for one of the triggers specified in Simple Trigger or Calendar Trigger. The trigger determines how often the alert runs and the date and time at which it runs. |
|
A container for the properties that define the repository URI of the report to run parameters. For more information, see Source and Input Controls. |
|
The default value is |
|
It contains a list of output formats, each to be generated in a separate output file when the alert is triggered. The possible values depend on the resource and the exportTypeabove. Report ( The XLS and XLS_NOPAG (Excel 2003) output formats are deprecated. You can use XLSX and XLSX_NOPAG (Excel 2016) instead. |
|
The time zone to use when running the report, for example "America/Los_Angeles". By default, the alert is set on the report using the server's default time zone. The time zone names are those supported by The trigger time zone and output time zone have different purposes even when they are often set to the same value. The trigger time zone determines when the alert is scheduled to run. The output time zone affects anytime or date calculations in the report. The time zone specified in a data source also affects the time and dates in the output. |
|
The locale to use when running the report. By default, the alert is scheduled using the server's default locale. If the report is not based on a Domain with locales, this value has no effect. Use a Java locale string that is also defined in your Domain, for example |
|
The basename of the file for the generated report alert output. Each output format appends its corresponding file extension to this name. This name may also have a time stamp appended as specified in Alert Output Properties. This final output name is then used in all locations where the file is saved: repository, file system, FTP, and email attachment. |
|
A container for properties that define the folders and filenames for the output files that are generated each time a scheduled alert runs successfully. Its properties are defined in Alert Output Properties and the optional FTP Output. |
|
A container for properties that define email recipients when an alert runs successfully. You can customize the contents of the email and whether the report output files are sent as attachments or links. For more information, see Alert Output Email. |
|
A container for properties that define system status when an alert runs successfully. You can customize the contents of the email and whether the report output files are sent as attachments or links. For more information, see Alert Output Email. |
|
If an alert fails, the |
|
If an alert is successful, then only the |
Source and Input Controls
The source is the report being scheduled by the alert along with any required input controls.
Property (as input) | Description |
---|---|
|
A mandatory property that defines the repository URI or the report options to schedule an alert in the report. The repository URI is relative to the scope of the user credentials used to authenticate the REST call. |
|
A container for the input controls (filters) for an alert. Every required input control in the report must have a JSON list item within |
Simple Trigger
The following properties define the recurrence pattern for a simple trigger.
Property (as input) | Description |
---|---|
|
A container for the following properties, itself contained in a required |
|
The timezone for all dates and times used by the trigger, for example |
|
The name of a previously defined exclusion calendar. An exclusion calendar defines a set of dates or times when the alert cannot be scheduled. For example, a list of holidays. You can update the exclusion calendar without changing the alert. |
|
Determines when the alert becomes active and sets the base time at which recurrence starts. Supported values:
|
|
The date and time at which the alert is scheduled to start, required when |
|
The date and time at which the alert stops. The trigger does not fire after this time, even if any occurrences remain unless a misfire occurs, and the misfire policy allows it. The format is "yyyy-MM-dd HH:mm" and the timezone property is applied. |
|
An integer value that defines the behavior if the trigger did not fire when scheduled. The values of A misfire occurs if the alert is inactive or when there are no available threads in the Quartz thread pool for executing the alert. The different trigger types have different misfire instructions available to them. By default they use a 'smart policy' instruction - which has dynamic behavior based on trigger type and configuration. When the alert starts, it searches for any persistent triggers that have misfired, and it then updates each of them based on their individually configured misfire instructions. |
|
An integer that defines how many times the trigger fires, provided the recurrence intervals happen before the |
|
The time interval between firings of the trigger, with the interval unit provided in the next property. |
|
The unit of time for the recurrence interval. Supported values: |
Choose a misfire policy based on how critical it is and how frequently you want to get notified about the alert. For example, an outage may last 1-2 hours, and if a daily report is critical, then you might want to get notified about the alert as early as possible. But, if a report runs every hour, then you might want to ignore missed alerts on the reports and wait for the next alert at the scheduled time.
|
Different policies might have the same effect depending on how the trigger is defined. Also, the same policy may have different effects on different trigger types. |
Calendar Trigger
A calendar trigger lets you schedule an alert to run multiple times based on any combination of time and date. Its properties let you define single values, ranges, or wild-cards for minutes, hours, days, weeks, or months. For example, you can run a report every 15 minutes from 10 AM to noon every Monday.
The following properties define the recurrence pattern of a calendar trigger:
Property (as input) | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Specifies the minute or minutes at which the trigger fires on a given hour. The value can consist of the following tokens:
|
||||||||||||
|
Specifies the hour or hours during which the trigger fires on a given day. All hours are specified in a 24-hour format. The value can consist of the following tokens:
|
||||||||||||
|
A list of "months": { "month": ["1", "11", "6"] } |
||||||||||||
|
Determines how the trigger days are defined:
|
||||||||||||
|
Specifies a list of days of the week on which the trigger fires, which has to be repeated every week. This is required if "weekDays": { "day": ["1", "4", "6"] } |
||||||||||||
|
Specifies the days of the month on which the trigger fires, to be repeated every month. This is required if
|
Choose a misfire policy based on how critical it is and how frequently you want to get notified about the alert. For example, an outage may last 1-2 hours, and if a daily report is critical, then you might want to get notified about the alert as soon as possible. But, if a report runs every hour, you might want to ignore missed alerts on the reports and wait for the next alert at the scheduled time.
|
Different policies might have the same effect depending on how the trigger is defined. Accordingly, the same policy might have different effects on different trigger types. |
misfireInstruction | Description for Calendar Triggers |
---|---|
0 (default) |
No instruction (same behavior as option -1 below). Does not trigger the alert that misfired, and takes no action. As the trigger did not fire, the number of occurrences is not decremented. This is the default behavior when no |
-1 |
Ignore misfire policy. Instructs the alert that the trigger is never evaluated for a misfire situation. In such cases, the alert simply tries to fire the trigger as early as possible. Subsequently, it then updates the trigger as if it had fired at the correct time. This value has the same effect as 0: take no action and do not change the number of occurrences. |
-999 |
Called the smart policy. Instructs the alert that on a misfire situation, the custom |
1 |
Run now: instructs the alert that on a misfire situation, the trigger wants to be fired now by the alert. |
2 |
Instructs the alert that during a misfire situation, the SimpleTrigger has to be rescheduled to 'now' (even if the associated calendar excludes 'now') with the repeat count left 'as-is'. This follows the trigger end-time, so if 'now' is after the end-time, the trigger does not fire. |
3 |
Instructs the alert that on a misfire situation, the SimpleTrigger has to be rescheduled to 'now' (even if the associated Calendar excludes 'now') with the repeat count set to any value, if it had not missed any firings. This does follow the trigger end-time, so if 'now' is after the end-time, the trigger does not fire. |
4 |
Instructs the alert that on a misfire situation, the SimpleTrigger has to be rescheduled to the next scheduled time after 'now' - considering any associated Calendar with the repeat count set to any value, if it had not missed any firings. |
5 |
Instructs the alert that on a misfire situation, the SimpleTrigger has to be rescheduled to the next scheduled time after 'now' - considering any associated Calendar with the repeat count left unchanged. |
Alert Output Properties
The output properties define the folders and filenames for the output files that are generated each time a scheduled alert runs successfully.
Property (as input) | Description |
---|---|
|
A container for the following properties. |
|
A boolean that determines whether the alert output is written as file resources in the repository. The default value is true. Use the next two parameters to specify the location of the files. When false, no alert output is written to the repository, local file system, or remote FTP. The output files are then only sent by email. |
|
Defines a default alert report folder in the repository of the alert owner. The output file resources are saved in this path: "defaultReportOutputFolderURI":"/some/folder/uri". |
|
A boolean that determines if the output is written to the default folder: "usingDefaultReportOutputFolderURI": {true|false}(these folders can be configured as described in the JasperReports Server Administrator Guide). By default, this is false and you must specify the |
|
Defines a folder in the repository where the output file resources are saved in this path: "folderURI":"/some/folder/uri". This repository URI is relative to the scope of the user who authenticates the REST call. This property is required if you do not use the default output folder above. |
|
A string that becomes the description of the alert output file resources in the repository. The description is used as it is by all output resources. |
|
A boolean that indicates if a timestamp is to be added to the names of the alert output resources. The timestamp added to the output resource names are created from the alert execution time using the specified pattern. The default value is false. |
|
A string containing "yyyyMMddHHmm" tokens to append a timestamp to the base filename. This takes effect if |
|
A boolean to determine the behavior when a newly generated output file has the same name as a previous one. When true, the alert owner does not have the permission to overwrite an existing resource, and the alert execution fails. When false, the alert fails if the repository already contains a resource with the same name as one of the alert output resources. The default value is false. |
|
Specifies a path in the local file system (of the JasperReports Server host) under which alert output resources would be created. The local path is the path in the JRS host's local file system. This functionality is by default disabled and this field is ignored. You can enable it in the file .../WEB-INF/applicationContext.xml, by setting the |
|
It contains parameters for writing alert output files to a remote FTP location. For more information, see FTP Output. |
FTP Output
You have the option to specify output to a remote server through FTP (File Transfer Protocol). When specified, FTP output is always in addition to repository output, and the output is written to both the repository and the FTP location. The file names to be written are the same as for the repository, therefore the baseOutputFilename, and sequential pattern must be valid on the FTP file system. The file overwrite and sequential filename behavior also apply to FTP output.
Specify the FTP server, authentication, remote path, and other FTP settings in the following properties:
Property (as input) | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
A container for the following properties, itself contained in repositoryDestination. |
||||||||||||
|
The type of FTP connection requested: ftp (default), ftps, or sftp. |
||||||||||||
|
The domain and host name of the FTP server, for example "ftp.example.com". |
||||||||||||
|
Integer value that specifies the port number of the FTP server. The default value depends on the connection type: ftp = 21, ftps = 990, and sftp = 22. |
||||||||||||
|
The login username for the FTP server. |
||||||||||||
|
The login password for the given userName on the FTP server. |
||||||||||||
|
The path of the folder under which the alert output resources should be created. |
||||||||||||
|
Specifies the security mode for FTPS. If true, then it is implicit (default), and when false, it is explicit. If the implicit is true, the default port is set to 990. |
||||||||||||
|
Specifies the secure socket protocol to be used, for example SSL or TLS. |
||||||||||||
|
Specifies the PROT command for FTP. Supported values are:
|
||||||||||||
|
Specifies the protection buffer size: a decimal integer from 0 to (2^32)-1. The default is 0. |
||||||||||||
|
When using SFTP authentication, store the SSH key file in the repository and specify its repository URI in this property. For more information about securing files in the repository, see the JasperReports Server Administrator Guide. |
||||||||||||
|
When using SFTP authentication, specify the passphrase for the SSH private key file stored in the repository. |
Alert Output Email
When an alert runs successfully, the properties in mailNotification specify email recipients for the report output files. You can specify subject and body content, and you can choose to send output as attachments or links. However, if an alert fails, no report output is sent.
Property (as input) | Description |
---|---|
|
A list of addresses to which alert output emails are sent. This property is required if you are sending an output email. |
|
A list of addresses to which alert output emails are CC'd. |
|
A list of addresses to which alert output emails are BCC'd. |
|
A string that is used as a subject line for all output emails from this alert. |
|
A string that is used in the body of output emails for the alert. At alert execution time, links to the output and errors might get appended to the notification message text. |
|
Determines whether the notification would include the alert output as attachments, or include links to the output in the repository. Each value has a different behavior and you must set this property based on your other properties:
|
|
A boolean that specifies whether the email notification should be skipped for alert executions to the produce empty reports (successful completion but no content). The default value is false. |
messageTextWhenAlertFails
(optional) |
The text of the email notification when the alert fails. At alert execution time, links to the output and errors might get appended to the notification message text. |
(optional) |
A boolean that specifies whether the mail notification should be send if the alert fails. The default value is false. |
|
A boolean that specifies whether the mail notification would include a detailed stack trace of an exception. The default value is false. |
Alert DataPoint
When an alert runs successfully, the properties in datapointalert specify the numeric values of the report using which the alert is created. You can specify the following values to create an alert in the report.
Property (as input) | Description |
---|---|
(required) |
A container for the following properties. |
id
(required) |
The ID of the alert data point assigned by the server. |
version
(optional) |
An internal version number, which is used for optimistic locking of an alert data point object. |
(required) |
Specifies the name of the data point alert. |
(required) |
Determines the element UUID from the report on which the alert is created. |
(required) |
Supported values are: |
(required) |
The value for which the alert should be triggered. |
(required) |
The supported values are numeric. |
(required) |
The report URI on which the data point is present. |
Recommended Comments
There are no comments to display.