|
|
|
|
|
|
Jobs are collections of related steps which perform simple to complex tasks as a single unit. There is no limit to the number of steps that a job may contain or the types of steps that a job may contain. Upon completion jobs can be made to notify recipients via email on either success or failure and can include diagnostic reports.
Jobs are queued for execution either manually or by means of an automatic impeller. Impellers can be schedules, payloads, messages, or changes to files in the file system.
It is important to note that jobs are executed in serial and not in parallel. This prevents jobs from spawning multiple instances of themselves and attempting to read/write a single resource simultaneously.
To create a job, select and expand an Agent node from the navigation tree view. Then right-click the jobs collection and choose Add New Job... at which point you will be prompted for the name of the job. Job names must be unique within an agent but not within the system as a whole. Upon supplying a valid job name the job editor will appear in the context pane for further customization.
To edit a job, select the job name node in the tree view navigation pane to open the job editor in the context pane.
At the top of the editor is a tool strip with the following buttons and information:
•Check Out: The check out button only appears when the job is not currently checked out. Pressing this button will place a design lock on the job. When the job is locked, only the user that placed the lock can edit the job and all updates are pending until the job is checked in.
•Rollback: The rollback button only appears if the job is currently checked out to the current user or the job is checked out and the current user is a system administrator. Pressing this button will remove the design lock from the job. If any design changes were made to the job while it was checked out, the changes are discarded. Only the user that has the job checked out and system administrators can rollback the job.
•Check In: The check in button only appears if the job is currently checked out to the current user. Pressing this button will remove the design lock from the job. If any design changes were made to the job while it was checked out, a backup of the job is created and the changes become permanent. Only the user that has the job checked out can check in the job.
•Update: Pressing this button will validate and save the contents of the editor to the database. If the job is checked out, the changes will not take effect for others until checked in.
•Macros: Pressing the macros button will provide a list of all of the processing tokens and macro functions that may be used in job steps to dynamically process data at runtime. Tokens and macros are supported in any field which has a yellow background.
•Conceal: Pressing this button will generate macro-safe encrypted and encoded values for sensitive information in macro commands and parameters.
•Refresh: Pressing this button will refresh the job from the database. All changes in the editor that have not been updated will be lost.
•Restore: Pressing this button will present a data grid allowing the job to be restored from a backup stored in the database. Pressing the Restore button will restore the Job. Restoring a job will take effect immediately. If the job is checked out, pending changes are not lost and the job will remain checked out. The XML definition of the Job backups and the Job can be compared in a side-by-side window to view the differences either incrementally or as a whole since a specific backup. Clicking the Compare to Latest button will compare the selected backup and the current Job as it exists in the database. Clicking the Compare to Next Backup button will compare the selected backup to the next newest backup, or the current job if no other backups exist.
Jobs have the following attributes which can be modified through the editor.
Information area:
•Job Name: The name of the job. Job names must be unique by agent. Job names can be changed at any time and changes will be immediately reflected in the job history.
•Job Description: A textual description of the job.
•Enabled for Processing: By default, a job is not enabled and must manually be enabled. If a job is not enabled, it cannot be automatically executed. It may still be executed manually. If a job is enabled, it still will not be executed automatically unless the agent to which it belongs is also enabled.
Designer tab:
•The designer tab is used to manage each job step in the job. Selecting a job step from the job step tree view on the left will display a job step editor in the content area of the tab page. Changes to each job step will persist in the editor until the job is saved or the changes are discarded. See Working With Job Steps for more information.
Parameters tab:
•Parameters: The parameters collection allows the job creator to create a set of name/value pairs which may be accessed throughout job execution using the <PARAMETER> macro function. Parameter values may be overridden by the impeller that triggers job execution to allow a single job definition to perform an unlimited number of work permutations. Parameter values set at the Job level may be overridden by parameter values set at the Impeller level. Parameter values set at the Job or Impeller level may be overridden by parameter values set at the Job Step - Parameter Editor level.
Work Folder tab:
•Source File: When a job is executing there are tokens that are provided to job steps that inform them how the job was launched and provide such information as access to system variables, specialized functions, and the name of a source file that triggered the job. When a job is invoked manually for testing purposes it may be desirable to set this value in advance so that you can simulate what the job would do when invoked automatically by an impeller that sets the source file.
•Parallel Execution Blocking: This setting determines how parallel executions are performed when the Agent is configured with a Processor Execution Threads value greater than 1. It is very important to understand the impact of this setting. Allowing jobs to run in parallel may cause problems it the jobs share resources (such as databases or files) and the use of hard-coded paths in variables can lead to dangerous, unintended consequences.
•A value of Agent means that a job can be executed if no other work in queue have their Parallel Execution Blocking also set to Agent. If multiple work items exist in the queue with Agent scope eligible work items will be prioritized by queue date and executed one at a time.
•A value of Job means that a job can only have one work item executing at a time. If multiple work items exist in the queue with Job scope eligible work items will be prioritized by queue date and executed one at a time. This setting does not prohibit work for other jobs from processing.
•A value of Impeller means that a job can only have one work item per Threads value per impeller executing at a time. If multiple work items exist in the queue with Job scope eligible work items will be grouped by impeller, prioritized by queue date, and executed one at a time. This setting does not prohibit work for other jobs or other impellers on the same job from processing
•A value of None means that no blocking will occur and parallelization will be limited only by the lesser of the number of execution threads allocated to the agent or the number of threads configured in the Threads box.
•Priority: This setting controls the priority a job is given at the time of execution when allocating available threads. Work is scheduled in order or Highest, High, Normal, Low, Lowest.
•Maximum Retries: This option allows a failed job to retry all steps from the beginning up to a specified number of failed attempts. The default is zero and the maximum is 99. During retry all the job steps are retried (even those that previously succeeded). In the event that the retry threshold is exceeded the job fails. If the job is able to complete work on one of the retry attempts the job will report success as the outcome but the step failure details will be retained in the generated job log. Because it is possible to re-execute steps that previously executed successfully and had lasting impacts it is recommended that job step level retry thresholds be employed instead of job level retry thresholds. For example, if the first job step is to save the file locally (which succeeds) and the second step is to process the file (which fails) then if Maximum Retries is set at this level the first job step would repeat successfully, resulting in more than one instance of the file being saved locally.
•Work Folder Usage: Controls the behavior of the automatic temp folder provisioning system used to provide a clean working folder scoped to an individual unit of work with automated cleanup abilities to reduce clutter and protect sensitive information. Populates the {UNITY-WORK-FOLDER} token with the name of specific folder during job execution.
•A value of None indicates that automatic work folder usage is disabled. The value of {UNITY-WORK-FOLDER} will an empty string.
•A value of Temp indicates that automatic work folder usage is enabled and uses environment configuration to determine the location of the work folder. The value of {UNITY-WORK-FOLDER} will be the fully qualified path to the temporary files folder for the execution context.
•A value of Agent indicates that automatic work folder usage is enabled and used the path specified at the agent level. The value of {UNITY-WORK-FOLDER} will be determined from the Work Folder Path on the parent Agent. If the parent Agent is not configured the fully qualified path to the temporary files folder for the execution context is used.
•A value of Custom indicates that automatic work folder usage is enabled and a custom base work folder path is provided. The value of {UNITY-WORK-FOLDER} will be the fully qualified path as derived from Work Folder Path.
•Work Folder Path: This is the base path used when the Work Folder Usage mode is set to Custom when generating the value of {UNITY-WORK-FOLDER}. If left blank the system temp path will be used.
•Work Folder Retention: Determines the behavior of the automatic cleanup routine when a job completes execution.
•None: Indicates that automatic cleanup will completely remove the contents of the folder specified by {UNITY-WORK-FOLDER} when the job completes regardless of success or failure.
•Success: Indicates that automatic cleanup will retain the contents of the folder specified by {UNITY-WORK-FOLDER} if the job succeeds; otherwise it will be completely removed..
•Failure: Indicates that automatic cleanup will retain the contents of the folder specified by {UNITY-WORK-FOLDER} if the job fails; otherwise it will be completely removed.
•Always: Indicates that automatic cleanup will retain the contents of the folder specified by {UNITY-WORK-FOLDER} when the job completes regardless of success or failure.
Notifications tab:
•Mail Account Override: The pasUnity Account which is designated as being responsible for sending SMTP mail messages and job logs during job execution. If not set to a valid account, then job steps that rely on SMTP operations will use the Mail Account configured on the agent to which the job belongs.
•On Success Email: A list of semi-colon or comma separated email address entries for recipients to be notified upon successful execution of the job. Notifications are sent using the SMTP settings configured on the job or the agent to which the job belongs.
•Success Log Detail Level: The level of detail to include on an email in an HTML table when a job succeeds. Valid values are Full, Enhanced, Normal, Minimal, or None.
•On Failure Email: A list of semi-colon or comma separated email address entries for recipients to be notified upon failed execution of the job. Notifications are sent using the SMTP settings configured on the job or the agent to which the job belongs. In the event of a failed execution job logs are also written to the Windows Event Viewer in the Application log.
•Full: All work events that occur during the job are included in the HTML table output - nothing is suppressed.
•Enhanced: Critical and warning messages and job component event delineators are included - informational messages are suppressed.
•Normal: Critical messages and job component event delineators are included - informational and warning messages are suppressed.
•Minimal: Only job success notification is provided - all other information is suppressed.
•None: No HTML table of job events is generated.
•Failure Log Detail Level: The level of detail to include on an email in an HTML table when a job fails. Valid values include the following:
•Full: All work events that occur during the job are included in the HTML table output - nothing is suppressed.
•Enhanced: Critical and warning messages and job component event delineators are included - informational messages are suppressed.
•Normal: Critical messages and job component event delineators are included - informational and warning messages are suppressed.
•Minimal: Only impeller failure or job step failure events are included for a compact view of why a job failed - all other information is suppressed.
•None: No HTML table of job events is generated.
•Include Job Log in Success/Failure Notifications: This option will inject a detailed job execution log in the form of an HTML table in the body of the notification sent by pasUnity upon job completion.
Key Value Pairs tab: Provides storage for values associates with key names unique at the object and level where they are defined and allow for value persistence between job executions.
•Refresh: Will refresh the display with the latest values from the database (also F5 can be used).
•Add: Allows you to provide the Key portion of a new key/value pair which will be added to the database with a blank value.
•Key Value Pair Grid: Displays the currently configured key value pair names and values.
•Last Modified: The last date that a Key Value Pair was updated.
•Key: The unique key name for the Key Value Pair.
•Value: The current value for the Key Value Pair.
•NOTE: If a key value pair is referenced in code or by a macro and does not exist it will be created.
Lookups tab:
•The lookups tab will only be visible if you have pasPortal security enabled. It is used to specify a list of mapping lookup items that downloaded from pasPortal and cached during job execution to provide high speed access for the Lookup macro.
•Name: The name to assign to the cached lookup table. Must be unique within the job.
•Mode: Determines whether the lookup is located by ID or by path. The value Exact will appear when the lookup is located using ID. In this mode the task can be edited and renamed within the pasPortal and the task will still be found and updated. The value Dynamic will appear when the lookup is using a path. In this mode the path can be parsed and include parameters and macro commands and will be resolved at runtime. While flexible, this mode can fail to find and lookups if they are renamed or if the path string is not valid.
•Lookup: The name (and path) of the lookup in the pasPortal that will be cached. The path string takes the form DashboardCode\LookupName and any change to either will not automatically be reflected by Dynamic targeting.
Tasks tab:
•The tasks tab will only be visible if you have pasPortal security enabled. It is used to specify a list of task items that are submitted to the pasPortal upon job completion. Regardless of whether a job succeeds or fails it will still send tasks to the pasPortal. It is critical that the system is configured with a pasPortal account with permissions to update the tasks you configure. If tasks are configured but fail to update for any reason the job will still complete and will record the task recording failure in the job log but this will not cause the job to fail.
•Condition: The condition for which the task notification will be applied. Success only registers on job success, Failure only registers on job failure, Completion registers regardless of the job outcome, and None will not register at all.
•Log: If checked the results of the job execution are included in the event entry.
•Mode: Determines whether the task to update is located by ID or by path. The value Exact will appear when the task is located using ID. In this mode the task can be edited and renamed within the pasPortal and the task will still be found and updated. The value Dynamic will appear when the task is using a path. In this mode the path can be parsed and include parameters and macro commands and will be resolved at runtime. While flexible, this mode can fail to find and update tasks if they are renamed or if the path string is not valid.
•Task: The name (and path) of the task in the pasPortal that will be updated.
•Event Date: This is the date for which the task event recording is performed. If left blank the current date will be used.
•Outcome: The outcome indicates whether the task is marked as success or failure. Valid values for success include SUCCESS, TRUE, and YES. Valid values for failure include FAILURE, FALSE, and NO. If the value is left blank the outcome of the job execution (either SUCCESS or FAILURE) will be used automatically. Case does not matter.
Notes tab:
•Notes: A free-form, multi-line place to record job-related notes in rich-text format to preserve fonts, formatting, and other layout.
Permissions tab:
•The Permissions tab will only be visible if pasPortal Integrated Security is enabled during System Configuration. For a detailed list of the available permission types available at this level refer to the Permissions topic.
After making changes be sure to press the Update button to save your changes.
To conceal sensitive information in macro commands and parameters use the Conceal button to generate macro-safe encrypted and encoded values.
While editing the job a red exclamation point may appear indicating there is an error with the configuration. Hover over the red exclamation point to find out how to fix the error.
Jobs can be copied to other agents in the system or within an agent to a new name. To clone a job, select and then right-click the job node in the tree view navigation pane and choose Clone... at which point you will be prompted for a target agent and a new job name. The job name must be unique within an agent but does not need to be changed when copying to another agent. The clone feature can NOT be used to overwrite existing jobs. If the clone impellers option is selected the impellers will also be copied along with the job steps. To prevent accidental execution of jobs and job steps the cloning process disables the job, all job steps, and the cloned impellers which will need to be enabled manually before automatic execution will occur.
To remove a job, select and then right-click the job node in the tree view navigation pane and choose Delete... to to remove it from the user interface and mark it as disabled. It can be restored using the Recycle Bin.
Deleting a job will also delete all job steps, schedules, impellers, and job history that has been stored. It is not advised that jobs be deleted if this information needs to be maintained. In such cases it is recommended that the job is disabled in the user interface.
Jobs can be moved to other agents in pasUnity. To move a job, select and then right-click the Job Name node in the tree view navigation pane and choose Move... at which point you will be prompted to select the target agent. The job name must not already exist on the agent you are moving the job to.
To export a job, select and then right-click the Job Name node in the tree view navigation pane and choose Export... after which you will be prompted for a file name to save the job into. You may then copy this file to another machine with a version of pasUnity newer or equal to the one from which you made the export file for importing.
To import a job, select and then right-click the Jobs node of an agent in the tree view navigation pane and choose Import... after which you will be prompted for a file name to import from. If any errors are encountered during the import process all changes will be abandoned.
NOTE: Not every option will be available for export for all jobs. For example, some impellers or job steps may make reference to other dependent objects (such as accounts and matrices) which are not included in the export file. Configuration items with these types of dependencies will not necessarily get exported/imported and may need to be entered manually.
To remove the hold from any work that might be in the queue for a specific job, select and then right-click the Job Name node in the tree view navigation pane and select Remove Hold on Work from the context menu.
•Interactive Execute: To manually execute a job on the current machine select and then right-click the job node in the tree view navigation pane and choose Interactive Execute... to execute the job and view trace data and messages in the trace pane at the bottom of the user interface. This option will not be available unless you are logged on to the agent machine. If you are working remotely you must use the Background Enqueue... option instead.
•Background Enqueue: To enqueue a job for immediate execution by the pasUnity Processor Agent right-click the job node in the tree view navigation pane and choose Background Enqueue... to create a temporary impeller and add the job to the work queue.
NOTE: A job executed by an impeller or via background enqueue may produce different results than when the job executes via manual means. When interactively executing jobs the jobs run in the security context of the logged on user and not that of the pasUnity Processor Agent service account. Also, some job steps only perform work when invoked as the result of a specific impeller. For example, a job which saves an attachment file from an email can only perform work when the job is invoked by a message impeller.
NOTE: A job may also be executing directly from a schedule or remote impeller by using the same options described above from the impeller node instead of the job node. The difference in impeller type will be noted in the job log and the parameter defaults from the impeller will be used instead of those from the job itself.
Lists the actions and outcomes of the specific job. The data grid shows execution history (success and failure attempts). Job logs are available for each line item by clicking on the Log button. To remove an item from hold status double click on the check box in the hold column for the row. This will allow the held work to reprocess. Clicking the column headers on the grid will sort the grid. Clicking twice changes the sort from ascending to descending. Pressing F5 will refresh the contents of the grid from the database. For information on system level History see Working with Activity.
Copyright © 2024 pasUNITY, Inc.
Send comments on this topic.
