Jobs
Jobs
A job is a report that has been scheduled to run automatically. In order to schedule a report, a user needs to have the schedule_jobs permission. Once logged in, a user's jobs are available from the Jobs menu.
Scheduling a new job
Take the following steps to schedule a new job
- From the Reports page, select the report to schedule and once the "select report parameters" page appears, click on the Schedule button. You can also schedule a job by going to the Reports Configuration page, finding the report to schedule and selecting the More | Schedule option.
- Specify the job details and Save
- The job will now run as per the schedule defined
| Field | Description |
|---|---|
| ID | Auto-generated ID used to identify the job |
| Name | Name of the job |
| Description | A description for the job |
| Job Type | The job type |
| Output Format | The output format for the job |
| Active | Whether the job can run or not |
| Number of Runs to Archive | For publish jobs, indicates how many runs should be retained for viewing from the View | Archives page e.g. setting it to 5 will retain output from the last 5 runs in the Archives page. This allows users to access past job output as per their requirements. |
| Allow Sharing | For publish jobs, whether the job output can be accessed by other users, apart from the job owner |
| Allow Splitting | Whether rule values for shared users should be applied so that each user gets different output |
| Fixed File Name | The base file name to be used for generated output. To include the burst id when used with a Burst Job, use the identifier {burstId}. This base file name does not include the extension. The extension will be automatically provided depending on the report and output format. File names can only contain english alphabet letters, numbers, hyphen and space. Any other characters will be replaced with underscores. Leave this field blank to use a default generated file name. |
| Dynamic Destination | For Burst jobs, a name or alternative name for a dynamic destination to be used by the burst output. Use the {burstId} identifier to indicate the burst id e.g. "Branch {burstId}" will send burst id 001 to a destination with the name or alternative name "Branch 001" if it exists, burst id 002 will be sent to destination "Branch 002" and so on. |
| Destinations | Any destinations to which the generated output should be sent. Destinations are configured from the Configure | Destinations menu. |
| Sub-Directory | An additional sub-directory that should be used with destinations. You can use the {burstId} identifier with Burst Jobs. This would imply that each burst file is put in a different directory. |
| Batch File | The name of a batch file or script that should be run after the job completes. The batch file must exist in the WEB-INF\work\batch directory. You only set the file name in this field e.g. test.bat or test.sh. ART passes the file name of the generated output as the first parameter to the batch file so you can use this e.g. to copy the file to another location, a batch file may contain the following command - copy ..\export\jobs\%1 C:\temp. |
| Pre Run Report | The report id of an Update Statement report that should be run before the job is run. Multiple reports can be specified separated by commas. |
| Post Run Report | The report id of an Update Statement report that should be run after the job has run. Multiple reports can be specified separated by commas. |
| Code | An optional, additional identifier for the job. ART doesn't enforce the uniqueness of this field. |
| Error On Zero Records | Whether the job should throw an error if it's output has zero records |
| From | The email address that will be used as the "From" email address of an email job. If not specified, the From address of the appropriate smtp server will be used. |
| To | The email address to send job output to. Multiple addresses can be specified separated by , |
| Dynamic Recipients | A dynamic recipients report that specifies email addresses to send job output to, with the email addresses being obtained from a database query. |
| Cc | The "Cc" email address for a job. Multiple addresses can be specified separated by , |
| BCc | The "BCc" email address for a job. Multiple addresses can be specified separated by , |
| Reply To | The email address that will be used when a user clicks on Reply in the received email. If not set, the "From" email configured on the smtp server or job is used. Multiple addresses can be specified separated by , |
| Subject | The subject of the email |
| SMTP Server | The smtp server to use, if different from the one configured in the Settings page |
| Message | The body of the email |
| Manual | Whether the job will run on an automatic schedule or not |
| Schedules | The schedules with which the job should run. If a schedule is updated, the job's run schedule is also updated. If a schedule is selected, the individual schedule fields are not considered. |
| Schedule | This field is only used to populate the individual schedule fields, which can be modified thereafter. |
| Second | The second that the job should run. If not specified, defaults to 0. |
| Minute | The minute that the job should run. If not specified, defaults to a random minute (0-59). |
| Hour | The hour that the job should run. If not specified, defaults to a random hour between 3-6. |
| Day | The day of the month that the job should run i.e. 1-31. If not specified, defaults to every day. |
| Month | The month that the job should run. If not specified, defaults to every month. |
| Week Day | The day of the week that the job should run i.e. 1-7 or SUN-SAT. Note that you cannot specify both the Day and the Week Day. Specify one of the two, leaving the other one blank, or setting it to "?" |
| Year | The year that the job should run. If not specified, defaults to every year. |
| Time Zone | The time zone for the defined schedule |
| Start Date | The date when the job should start running. If blank, the job will start running on the current date, as per it's schedule. |
| End Date | The date when the job should stop running. If blank, the job will continue to run indefinitely. |
| Extra Schedules | Definition of extra schedules on which the job should run, in addition to the main schedule defined in the individual schedule fields. Schedules are defined as Quartz cron expressions, with each schedule on a new line. |
| Error Notification Email | An email address that should be notified if an error occurs while running the job. Multiple email addresses can be specified separated by commas. The SMTP server used is that configured in the Settings page. |
| Options | Options for the job. The options are specified in JSON format. |
Note:
- Not all report types can be scheduled
- If the output for a job creates a file e.g. publish to pdf, this file is stored in the WEB-INF\work\export\jobs directory
Options
A number of options can be specified in the Options field. These are defined in JSON format with the following possibilities.
| Property | Data Type | Description |
|---|---|---|
| minRecordCount | Integer | Minimum record count for the job, below which the job will throw an error |
| maxRecordCount | Integer | Maximum record count for the job, above which the job will throw an error |
Job Types
Email (Attachment)
The output is emailed as an attachment to the specified recipients (in the "To" section). The attachment type can be selected in the Output Format field.
Email (Inline)
The output is emailed to the specified recipients, in the email body.
Publish
The output is saved to a file. The file is reachable from the Jobs page. Once the file is generated, a notification email is sent to the specified recipients (in the "To" section). Leave the "To" area empty if you don't want a notification email to be sent.
Alert
Send an email to the specified recipients if the first column of the first row in the query result has a value greater than zero. You can construct a simple SQL query to return a non zero value in case of a certain business condition.
Example query to be used for an alert. Send an email if a big order is made
SELECT count(*)
FROM todays_order_details
WHERE quantity>100
Just Run It
Simply run the report. May be used to run stored procedures or perform data updates.
Conditional Email (Attachment)
If the result has records, an email with the output attached is sent to the specified recipients. If it has no records, no email is sent.
Conditional Email (Inline)
If the result has records, an email is sent to the specified recipients with the output contained in the email body. If it has no records, no email is sent.
Conditional Publish
If the result has records, the output will available from the Jobs page. A notification email is sent to the specified recipients if this is configured. If the result has no records, no output is available on the Jobs page and no email is sent.
Prints the report output to the default printer
Burst
Generates report files for each distinct value in the result. This requires that the query for the report be ordered by the first column, which will be the burst-id column. When the value of this column changes, a new file is generated. Burst jobs are only possible with Tabular reports. The files generated will have the burst-id in their file names so different files can be identified and copied or ftped to different locations for example. The generated files are located in the \WEB-INF\work\export\jobs directory.
Archives
For publish and conditional publish jobs, you can specify that a certain number of job runs should be archived i.e. files generated from past runs should be available for viewing. This is done by setting the Number of Runs to Archive field when defining the job, and archived files are available from the View | Archives menu.
Shared Jobs
By default, only the owner of a job has access to its output, particularly for published jobs. Shared jobs allow the output of a job to be shared with other users. To share a job's output, enable the Allow Sharing field and select the users or user groups with whom the output will be shared using the Configure | Access Rights menu. These users will be able to access the job's output from the Jobs menu.
Split Jobs
If the report for a shared job uses rules, you can specify that the rule values for the shared users be applied so that each user may get different output. To do this, enable the Allow Splitting field. If this field is disabled and the report uses rules, the rule values of the job owner will be applied and all shared users will get the same output. If the report doesn't use rules, the value of this field will have no effect.
Random Start Times
You may not need an exact time when a job runs, as long as it runs in a certain window of time. This may be useful to avoid very many jobs running at the exact same time. If you leave the Hour and Minute fields blank when creating the job, the job will be assigned a random hour between 3-6 and a random minute between 0-59 in which it will run. Additionally, you can specify an explicit time range in which the job should run. To do this, in the Hour field, define the required start time and end time separated by | e.g. 4|7, 4:30|6, 12:45|13:15. The job will then be assigned a random execution time in this range.
Quartz Properties
You can modify some aspects of the scheduler e.g. thread count by modifying the WEB-INF\classes\quartz.properties file. Documentation of configuration options can be found here.
Running Jobs
You can see which jobs are currently running by using the Configure | Jobs menu and then click on the Running Jobs button. If you want the page to refresh automatically, you can modify the url and add the refreshPeriodSeconds parameter e.g. http://localhost:8080/art/runningJobs?refreshPeriodSeconds=30. The minimum refresh period is 5 seconds.
