Job

Scheduler: Job

This is where you create and edit scheduled jobs. There are many different Job Types that you are able to run.

Service

Field	Type	Description
Status (Drop List)	Selection	New jobs default to 'active' by default and will run automatically when a stored Run Time is reached. Set jobs to 'inactive' if you do not want to run them anymore, or if you want to run the job on an 'ad-hoc' basis using the Run Now button. When you update a job to become 'inactive', check to see if there are any child jobs. When a parent job is made 'inactive', child jobs are made 'inactive' at the same time. Making a parent job active again will not update any children. They must be made 'active' again individually
Parent Job ID (Num)	Lookup	Enter or lookup a job that you want to add as the parent. Visit the Parent Job ID page for all the details feature details
Module (List)	Selection	Select the relevant module
Class (List)	Selection	Class category from gb_scheduler_types
Method (List)	Selection	Select the method that should be used in the job
Description (Text)	Text	Enter a description of the job
Parameters (Heading)	Variable	Different fields will display in the Parameters section depending on which "Method" you have chosen. Visit the Method page to find and read about the requirements for your chosen "Method"
Attachment Format (List box)	Selection	Choose the required format for the attachment file from 'Office(xlsx)', 'Office(xls)', 'Text (csv)', 'Text (txt)' or 'XML'. 'Office(xlsx)' is the default value

Mail

Field	Type	Description
Send Mail (Check Box)	Checkbox	Check this on if you want to send an email when the job runs. Each scheduler method has a default setting for this check box. See the set up page for more details. For some methods, it is disabled when emailing is not applicable. If the job's method is executeQuery, the email is sent to the stored recipients and they receive the executed query as an attachment in the email. For other methods, the purpose of "Send Mail" is to email the recipients to confirm that the job has run. This includes mail_query jobs. Use "Send Mail" if you want to receive a confirmation that the mail_query job ran, the mail_query email content itself is not visible on this screen. If this field is checked, the job will not save unless: a "Sender" is recorded, the job status is 'Active', there is at least one "Recipient" entered. If this field is unchecked: The "Subject" field is disabled, The "Sender" record is removed
Subject (Text)	Text	Enter the Subject line to display in sent emails. Note: the placeholder #SERVERNAME# can used and will be replaced by the value from the environment variable SERVERNAME at run time
Body (Text)	Text	Enter the text to display in the body of sent emails when the "Send Mail" field is checked. When it is unchecked, this field can be used to store comments
Use Standard Footer (Checkbox)	Checkbox	Tick the Checkbox ON to incorporate the mail footer stored in gb_controls mail_footer

Errors

Field	Type	Description
Type, Name, Address, Receipt Flag	Various	Enter the details of where error messages should be sent

Run Times

Minute, Hour, Day, Month and Weekday are multi-select boxes. Hold down the Ctrl key to select multiple values.

Warning: The schedule times take some getting used to. The combination allows the scheduling of re-occurring execution for any minute of any day of the year. For example, to execute a job at the end of the financial year, you would select 0 minute, 12am hour, 1st day, Jul month and All weekdays. New jobs do not have any run times set by default and must be set before saving. Jobs should generally not be set up to run every minute where possible. Users will be alerted with a pop up message if they have selected the run times to every minute.
If a Parent Job ID is entered, Run Times cannot be edited and will use the Parent Job Run Time parameters.
Important: Whilst it is possible to set run times to run a job every minute it is not recommended. Doing so may impair the system response times and slow down user work. It is recommended that if a job is run on a frequent basis, set as a minimum time to run on 15 minute intervals and limit to possibly working days as an example.

Field	Type	Description
Minute	Checkbox, List	Minute(s) of the hour to schedule this job
Hour	Checkbox, List	Hour(s) of the day to schedule this job
Day	Checkbox, List	Day(s) of the month to schedule this job. Choose 'EOM' if you would like the job to run on the last day of each month
Month	Checkbox, List	Month(s) of the year to schedule this job
Weekday	Checkbox, List	Weekday(s) of the week to schedule this job

Additional Fields

Field	Type	Description
Sender	Lookup	If an email is going to be sent when the job is run, select the user to show as the email sender. If you use the Run Now button, you will be shown as the email sender, and not the stored "Sender". If you are running mail_query jobs, the sender is defined in the query, those emails do not use the stored "Sender". Catch-e recommends using (or creating then using) a user called 'Scheduler' for all jobs (except those that need the "Sender" to be a particular person from your business). This means that your staff will know that the email came from a scheduler job, not an actual person
Linked To	Selection	Attach job results to this type of catch-e object
Record ID	Text	Attach job results to the catch-e object identified by this id
Report Queue	Checkbox	Check this to store the generated reports in the Report Queue. Recipients can be advised of the report, but will not receive it in the email. This is only available when the selected "Method" is executeQuery. The check box is disabled for all other methods
Recipients	Field Set	gb_scheduler_job_recipients to receive job results. A recipient must be added where the status is 'Active' and the 'Send Mail' check box is ON
Attachment Required	Checkbox	When checked, recipients will only receive an email if running the job generated an email attachment. If no file generates when the job runs, the email is not sent. This is checked by default for new jobs and can be unchecked
Next Due	Timestamp	Displays the date and time of the next scheduled run for this job. If you edit the job, this will show as unavailable for a couple of minutes until the job queue is refreshed with the new next run record. (where status = 'pending')
Recycling	Checkbox	If this check box is unchecked, all past job records are retained and can be viewed on the Scheduler / Queue tab. If checked, past records that are completed correctly are discarded and are no longer visible on the Scheduler / Queue tab except for: Any job queue records linked to a Mail Batch, The last 10 successful job queue records where no email has been sent, Any job queue records that failed, Any job queue records that aborted, Any job queue records where the service asked the scheduler not to recycle the queue item in its response (for example: an interface service found and imported a file, item is to be kept for reporting purposes for SLA)

Buttons

Top Buttons

Copy: Create a new job based on the current job
New: Create a new job

Bottom Buttons

Edit: Edit an existing job
Run Now: Click to run the job manually. Run Now is available for selected job methods only and requires an entry in gb_service_process_types. Refer to the Validations and Alerts Run Now section for issues you may see here. Run Now can run a chain of parent-child jobs, or you can opt to run just the selected job from within the chain. Refer to the Validations and Alerts Run Now - Job Chain section for the various selections

Edit Buttons

Cancel: When editing, click to cancel any changes you have made
Save: When editing, click to save changes you have made to the current job

Field Entry Validations

Send Mail / Report Queue Alert

Selecting "Send Mail" will disabled "Report Queue" and remove all linked recipients. Do you want to continue? OK / Cancel
A confirmation alert that is displayed when "Send Mail" is checked and "Report Queue" had been checked. Only one of these check boxes can be selected

Report Queue Unselect Alert

Unselecting "Report Queue" will remove all linked recipients. Do you want to continue? OK / Cancel
A confirmation alert that is displayed when "Report Queue" is unchecked

Save Validations

Validation Alert	Message
Invalid recipient address	Address is invalid. OK / Cancel - There is no populated Recipients: "Address". Enter an email address
Child jobs active	Child jobs are active: {job_id} These will be made inactive. Continue saving? OK / Cancel - If you want the child jobs to become inactive also, continue to save. Otherwise, cancel the editing you are doing and update each child job and separate them from the parent if they should continue to run. Visit the Parent Job ID page for all the details feature details
Missing mail sender	Mail sender is required. OK / Cancel - Select a "Sender" for this email

Run Now Validations

Error	Description
Process still running	Failed to run! Error: this process is still running! - The job is taking a long time to run. It will continue to run in the background until completion
Missing recipient	Failed to run! Error: A recipient is required - If you have clicked on Run Now and "Send Mail" is checked, you must have a valid recipient recorded in the job
Duplicate column names	Job failed! Error: CATCH-E ERROR DUPLICATE COLUMN NAMES Error message: Duplicate column names - The query has a duplicate column. Ask Catch-e Support to review and correct the query. The duplicate column will need to be removed or re-named
Malformed query	Job failed! Error: CATCH-E BAD QUERY - The query is mal-formed in some way. Ask Catch-e Support to review and correct the query
Billing lock error	Job failed! Error: CATCHEAPIEXECUTESCRIPT_ERROR Error message: Failure executing query #. Message: Statement could not be executed (45000 - 1644 - Billing already locked!) - The executeScript job started, but could not be completed. A billing lock could not be secured for one of the scripts in the query. The script number is shown in the message. Try again later

Run Now - Job Chain

Job has active children. Run child jobs also? The job is a parent, or is part of a chain of parent-child jobs. Click OK to run the job and it's children. To run just the selected job, click Cancel > 'Just run this job?' Click OK. Click Cancel to exit the process without running any jobs

Error	Description
Child job missing recipient	Failed to run! Cannot run this job because child job '{job_id}' must have at lease one recipient - Go to the named job and add a recipient to it
Child job aborted	Failed to run! Cannot run this job because child job '{job_id}' is aborted - You are trying to run a chain of jobs, but there is a job with an 'Aborted' status in the chain. Go to the Schedule tab and review the job chain. Review and fix any children that are 'Aborted' or 'Inactive'
Job inactive in chain	Failed to run! Cannot run this job because it is within a chain and is inactive. Either remove it from the chain or make it active - Go to the Schedule tab and review the job chain and update the jobs as required to either make them active, or separate them from the chain

Troubleshooting

Attachment Formatting Issues

If your scheduler job is using 'Office(xlsx)' as the "Mail Attachment", you cannot use a customised Format. Go to the Scheduler / Job and change the output format to be 'Office(xls)' if you want to create and use a customised Format.

Parent Job

The Scheduler / Job "Parent Job ID" field allows you to link the job to another as a 'child'. Child jobs run automatically after the parent job each time it completes successfully.

Run time parameters are not set in child jobs. This is determined by the parent.

Any job may be a parent or a child or both. Multiple jobs can be linked in this way.

To Review Linked Jobs

Go to Scheduler / Schedule
Enter the parent job id into the "Job ID" field
Check on the "Show all Children" check box
The parent job and its children will display on the screen
If the children are also parents, their children will also be displayed (and so on)
The jobs will display in cascade order (Parent, Children, Grandchildren, Great Grandchildren)

Setting a Parent Job to 'Inactive'

When a parent job is made 'inactive', child jobs are made 'inactive' at the same time. You will be alerted if this is going to happen. Continue with the process if making the child jobs 'inactive' is appropriate for the situation.

When you make a parent job active again, the child jobs do not update automatically (they will remain 'inactive'). You will need to edit each child and update their "Status" to 'active' again individually.

If you do not want the child jobs to become inactive, you will need to edit them and remove the "Parent Job ID" link. The child will retain the run time parameters that were held by the parent job. These can now be edited if required.

Queue

The queue screen displays entries from gb_scheduler_queue. It contains many entries for the majority of scheduled jobs listed in gb_scheduler_jobs. Filters are applied when the go button is clicked and all filters (except Job Queue ID) combine to provide the minimum results.

Filters

Filter	Type	Description
Job ID	Lookup	Locate gb_scheduler_queue entries of gb_scheduler_jobs_id type
Queue ID	Lookup	Locate a specific gb_scheduler_queue entry
Module	Drop List	Module category from gb_scheduler_types
Class	Drop List	Class category from gb_scheduler_types
Method	Drop List	Web service to execute
Slow Jobs	Checkbox	Displays jobs that ran for more than 30 seconds
Status	Drop List	Filter by gb_scheduler_queue status_flag

Columns

The column headers of this screen are dynamically sortable. By selecting the grey box header, the data will be sorted in an ascending order. If selected again, the data will be sorted in a descending order.

Column	Type	Description
Job ID	Number	System generated unique id
Queue ID	Number	System generated unique id
Type	Text	Module, class and method for the given scheduler_type_id
Scheduled Start	Date	Scheduled start date and time
Actual Start	Date	Actual start date and time
Actual End	Date	Actual end date and time
Duration	Time	Actual end minus actual start
Message	Text	Displays the message that was generated when the job ran. These mostly describe job failures or the reasons why a completed job did not generate a report or update as expected. Go to the Message page for a list of messages and explanatory comments
Status	Text	The status is 'Completed' if the job ran successfully and 'Failed' if it did not complete for some reason

Report Queue

The Scheduler / Job "Report Queue" check box allows you to send attachments directly to System / Report Queue. "Report Queue" is only available for the executeQuery method.

Behaviour of Report Queue Field

When "Report Queue" is selected, the "Recipients" section updates to show the appropriate fields for this function. If "Report Queue" is unchecked, the "Recipients" section will show the standard emailing fields.

When "Report Queue" is selected, it will not display "Type" and "Receipt Flag" fields. Instead, it will display "User" and "Notify" fields.

When a user is selected, their "Notify" check box will default to show the setting stored in their System / Users "Report Queue Notifications" checkbox. This can be updated if required.

When "Notify" is unchecked, the user will not be notified when the report is ready.

When "Notify" is checked, the user will receive an email when the job has run and the report is ready.

Recipients Fields When Report Queue Is Selected

Field	Type	Description
User	List	Only users that have access to 'Report Queue' screen will be shown in the lookup and can be selected. This can be identified from each role
Name	Text	Name of the user
Address	Text	Email address of the user
Notify	Checkbox	When 'Notify' is unticked, user will not be notified when report is ready for them in 'Report Queue' screen. If 'Notify' checkbox is ticked, user will be notified when job has run, and report is ready for them in 'Report Queue' screen

Recipients Fields When Report Queue Is Not Selected

Field	Type	Description
To	Text	Standard recipient field
Name	Text	Name of the user
Address	Text	Email address of the user
Receipt Flag	Checkbox	Attachment required indicator

Attachment Required Field When Report Queue Is Checked

If 'Attachment Required' is unticked and 'Notify' is ticked: user will be notified as soon as report has run even if there is no attachment. In Report Queue screen, it will show the report with no attachment
If 'Attachment Required' is ticked and 'Notify' is ticked: user will be notified only when there is an attachment

Please refer to the workflow chart in the Report Queue section to get more details about the Report Queue workflow.