Administration of Broadcast Jobs

JOBADMIN [-X] [owner1 owner2 ... ]

The JOBADMIN program provides local control over all aspects of broadcast job management. It allows creation and maintenance of clients and job instances, as well as monitoring and detailed management of job progress.  The command-line parameters select groups of owner folders as described below.

Important:  Job Property Hierarchy

It is very important to understand how job properties are combined from the System, Owner and Jobtype levels to create a job instance, and how they are edited in JOBADMIN.

Each of the System, Owner, and Jobtype pages normally shows only the properties defined at their specific level in the hierarchy.  When a property field is empty, no property will be added for that level when the levels are combined for a single job instance.  Other levels (above and below) may still properties of the same type which will be used when a job instance is created.
For Job Instance properties, the property field always shows the combined properties after System, Owner and (optionally) Jobtype properties have been collected together to create a job instance.  Once a job instance has been created, the properties in the System, Owner, and Jobtype records no longer affect what happens to the specific job instance.  When a property field is empty in a job instance, either the property is not defined or it takes a default value from the configuration file FAXFACTS.CFG.

To help you recognize what type or property page you are on, the text entries are color-coded as System, Owner, Jobtype and Job Instance.

On Owner property pages, you can left-click and hold the panel showing the Owner name to display temporarily the effective Owner properties, combining the System and Owner levels.  The owner name is followed by + to indicate that System properties are included, overridden by Owner properties.

On Jobtype property pages, you can left-click and hold the panel showing the Jobtype name to display temporarily the effective Jobtype properties, combining the System, Owner and Jobtype levels.  The jobtype name is followed by ++ to indicate that System properties are included, overridden by Owner and then Jobtype properties.

Even when a property field is empty, there may be default values defined in the FAXFACTS.CFG file, for example on a $retry_delays configuration command, or the properties may have a built-in default, such as 'two retries'.  These defaults are not shown in JOBADMIN, which only ever displays job properties.  Note that configuration default properties usually include a line-group parameter and may not affect all lines. You can suppress the use of CFG and built-in defaults in Job Administration by including job defaults in SYSTEM.UJP.

The temporary display of combined properties is shown with the bold and + or ++ title while you hold down the left button on Owner or Jobytype pages.  Job Instance pages always show the combined instance properties. The Editor page only ever shows level-specific properties.

Overview Page

The program starts with an outline view of clients and jobs, showing the current state of each active job.  This screen refreshes every minute.  Under Active Jobs, the list can be sorted by left clicking the column heading, once for ascending, again for descending.

When you double-click to select a job on the overview page, the tree on the left opens at the job, and the Overview page changes to a summary page for the job.  You can return to the overview at any time by clicking the Overview button in the top left corner.  The Active jobs lists is refreshed automatically at intervals if left visible, and if you click on a job which has been created since the main treeview was last refreshed, the treeview will be refreshed automatically also.  If the treeview contains a subset of owners only (selected using command-line parameters) you will not be able to select jobs for other owners from the overview page, though they will be shown there.

Some of the columns have a filter icon, and clicking this allows you to filter the table to show selected jobs only. When a filter is in operation on a column, the background color of the column header changes to yellow. In the case of the Status Time column the filter intervals are calculated when you select the filter, not every time that the list is refreshed with the filter applied.

In the main part of the window, you can change the order of the tabs by dragging them.  This may be helpful if your screen is not wide enough to display all the tabs and there are some that you use less frequently. The Overview and Summary tabs always remain at the left-hand end, and the right-click menu in the panel below the tabs allows you to restore the default sequence.

The right-click menu of the panel below the tabs also allows selection of the sequence in which job instance properties are displayed under each owner or jobtype in the treeview. The default is now to show them in descending sequence of job number, so that the newest job is next to its owner or jobtype properties.  The menu allows selection of ascending sequence instead which was the default in earlier releases:

System Job Properties

You can edit the System Job Properties to allow specification alternate names for Owner and Jobtype in the JOBADMIN program. For example if the main level in your CopiaFacts application is used for bureau clients, you can substitute "Client" for "Owner" using:

$title_owner "Client"

In the System job properties you can also select the columns which are to appear in the job item status list.  For example:

$status_columns      FSNUM RCVNM DELTO STATUS LASTA

For more information, see the $status_columns topic.

Treeview Section

The treeview in the left section of the window allows selection of system properties, owner properties, jobtype properties and job instance properties.  If you select a tab corresponding to properties selected on another machine, a brief warning pop-up is displayed and the properties are set to be locked, with a red panel at the top:

Each item in the tree has a right-click menu.  For the system, owner and jobtype properties, this allows creation of properties at the next level down. For job instance properties, the menu gives access to actions which will vary depending on the current status of the job.

When creating owners and jobtypes, you can 'clone' the properties of an existing owner or jobtype.  When creating a job instance, its properties are merged from the system, owner and if applicable jobtype properties above it.

The Treeview is only ever refreshed automatically at startup and when owners or jobtypes are added.  You can click the refresh button to refresh the treeview manually. Refresh on startup and on owner/jobtype addition disables the 'active owner' filter described below.

Owner Filtering

Users with large numbers of owner folders can set up owner filter lists to allow different operators to manage different groups of owners. Filter lists consist of one or more owner names with optional wildcard characters * and ?.  Owner filters can be specified in the filter dialog described below, or on the command line.  For example to select only owner names starting CTS and Copia:

JOBADMIN CTS* COPIA*

and to exclude these owners:

JOBADMIN -x CTS* COPIA*

When specified on the command line, owner filters override the last saved filter used.  Saved filters are created by right clicking the Refresh/Filter button.  The filter list always shows an 'all owners' entry and an entry for the command-line filters, if specified: these cannot be edited.  Other filters can be created and saved using the dialog and the same format as the command-line parameters is used (a blank-separated list, optionally preceded by -x for an exclusion list.

In addition to filtering by owner name, JOBADMIN also has the ability to show in the treeview only those (optionally filtered) owners who have 'active' jobs shown on the Overview tab.  This feature can make it much easier to find items in a shorter treeview list, but may very slightly increase the time taken to scan for active jobs and update the overview page.  It is disabled by default but can be enabled using the right-click menu available in the panel below the tabs.

The Refresh/Filter button has four modes:

When left-clicked it refreshes the existing selection of jobs.  When an 'active owners' filter is enabled, this happens in stages: first the treeview is refreshed, which then leads to a refresh of the active jobs list, which then allows the non-active owners to be hidden.  If a new job is created for a hidden owner outside JOBADMIN, it will be found when the Overview tab is refreshed and visited, but the owner will not appear on the Treeview until that is manually refreshed.

Control-left-click toggles the refresh between the selection specified by the active filter and the full display of all owners and jobs. The color of the top half of the button indicates whether an inclusion list (green) or exclusion list (red) is active:

Shift-left-click toggles the refresh between 'all owners' and 'all owners who have jobs visible on the overview tab'.  The color of the bottom half of the button changes to yellow if the 'active owners' filter is enabled.  At program startup this filter is always disabled, and the same happens on addition of a new owner or jobtype, so that the owner is not then hidden because it has no jobs. You can then shift-click the button to hide inactive owners.

Right-clicking the Refresh button brings up the owner filter dialog:

Only one filter can be selected at a time.  Filters from this dialog are saved in the registry, and the last filter selected from this dialog is saved as the active filter when you next open JOBADMIN.  Note that the saved filter is still re-used even if you have control-clicked the Refresh/Filter button to toggle temporarily the display of all owners and jobs.

Job Instances can be deleted from the right-click menu, but only if unstarted or finished.  JobType and Owner folders can only be deleted (also from the right-click menu) if an environment variable named JOBADMIN_DELETION has been set with value 'Allowed' and if the treeview element has no child elements.  The same environment variable also permits Job Instances to be deleted or archived at any stage, using control-shift-right-click to access the menu.

Job Summary

The job summary page summarizes the status of a job instance in more detail.  For an Owner or Jobtype record, only the top section is shown.  The fields in the top (job status) section cannot be edited here: clicking in one of the fields takes you to the page on which it can be edited.  [The example below shows as read-only, with a red panel, because the sample job status is completed].

The Job Statistics section only appears when there is data to report.

New job set-up and property changes

For new jobs being set up using JOBADMIN, and to modify existing jobs before launch, you can use the tabs to select the pages you need.  To select a job list, for example, go to the Lists page, select Active in the leftmost column, and right-click in the upper grid to show the file menu:

Clicking on a file in the top grid, will cause it to be displayed (read-only) in the lower grid.  The following color coding is used for columns:

RedPhone number for Fax, Voice, SMS, Poll broadcasts, and Fax+E-Mail two-column (FEB2)
GreenE-Mail address for E-Mail Broadcasts and Fax+E-Mail two-column (FEB2)
BrownFax and E-Mail single column (FEB1)
YellowRecipient Details (for $fax_receiver template command).

You can right-click in the list header row to bring up a menu which will select the broadcast type and the use of a specific column.  Selecting one of the menu selections modifies the Broadcast tab settings.

If job option OmitListHeader or WordMerge is enabled, the list will show two non-scrolling heading lines, one the BCFn values, and the other the header row from your list.  You can right-click in either line to get the header menu.  If you also have job option CreateBCXvars enabled, clicking the second line will insert variables @BCX_column in the corresponding command.

Right-Click in top header row

Right-Click in second header row

In any grid or edit field which can contain a filename, you can right-click to bring up a file open box.  If the filename column is the second column in a grid you will have to make an entry in the first column to enable the entry in the second column.

Other tabs contain either grids or field-oriented entry areas.  Pressing F1 in any grid or entry field brings up a relevant help page.

Full Editor Page

The Editor page gives access to the full content of the UJP file.  The editor is maintained in step with changes made on the other pages, and vice versa.

This page is the only one on which the Revert button appears, and to revert changes made on other pages you have to visit the editor page.  You may see the Revert button enabled even if you have made no changes: this is because the first time you use this version of JOBADMIN it may reformat the command spacing or sequence.

The editor includes the functionality of COPIAEDIT and provides both syntax highlighting and the ability to get help by double-clicking on a command keyword. Search, Replace and Undo functions are available using Ctrl-F, Ctrl-R and Ctrl-Z respectively.

If you highlight a filename in the editor and right-click it, then if the file can be found a pop-up menu line will allow you to view the file.  Most common file extensions are supported, and for files such as PDF or DOC an appropriate application must be registered to process the view.  Filenames without a path element are searched for in the appropriate locations.

Job Item Status

Active jobs can be displayed with the status of each item shown in detail. Right-clicking an item in the list brings up a menu which allows resubmission of failed transmissions and viewing or editing details of the item.  The column headings can also be left-clicked to sort the list in ascending or descending order, and right-clicked to filter the view on selected column content.

For use with very large jobs there is also a 'fast sort' feature, which is selected by holding the control key down while left- or right-clicking on a column heading to sort the list.  In this mode, the list is sorted (in a couple of seconds, even for a list with tens of thousands of items) without first refreshing all the items, and using the original values for such fields as Status, which may have changed. The items are, however, refreshed on display and on selection, so after doing a 'fast sort' you may see a few items which appear to be out of sequence, or where the Status value differs from that which would have been selected earlier by the Sent, Fail and Pending checkboxes.

Note in the example below that the Item Status page tab has been dragged to the left so that this page can be reached more conveniently when there is only space for a narrow window.  Also that the list for this example broadcast was edited and saved as Unicode with the Russian composers' names in Cyrillic script.  In this example the encoding for FS files was also set to Unicode.

The FS file editor accessed from the right-click menu is a cut-down version of COPIAEDIT and offers search and replace and undo capability.  As in COPIAEDIT, double-clicking a CopiaFacts command brings up help for the command, and double-clicking a double-quoted pathname opens the file in its associated application.

Job Actions

JOBADMIN permits a range of actions to be performed on each job instance, selected by means of a right-click on a job instance in the tree structure.  The menu is dynamically configured to show only the items which are valid for the job at the time.

Some of the above right-click operations may be time-consuming for large jobs and should be used with caution. In particular, the retry-failed operation is not designed for regular use to do 'one more attempt' at the end of a job: if you find this is done commonly, it should indicate to you that the retry parameters need to be changed instead.

'Retry Failed' Menu Item

This menu item pops up a further dialog to allow specific outcomes only to be retried:

If you have specified the job instance variable FAST_TOSEND_SCAN, the Resubmit Priority field is suppressed.  The priority used is then as specified by $retry_tosend if present, or the normal priority of the job.

Unicode

JOBADMIN is fully Unicode-enabled. When UJP files are saved, they will be saved with the encoding specified for USR/UJP files on a $unicode command in FAXFACTS.CFG.