Working with Agents




Agents are machines that host the pasUnity Windows Service components.  Agents are used to monitor folders, process jobs, collect messages from mail servers, and host XML-based web service endpoints, among other things.


If you are running in a shared configuration where multiple agents are configured to use the same SQL Server database to store their settings, you are able to remotely view and configure agent properties from the pasUnity user interface.  You are not permitted to remotely start/stop services or interactively execute jobs on remote agents.  If you have permissions, you may background enqueue work on all agents for certain impellers.


While agents are not required to be configured with an SMTP Account they will not be able to send success and failure notices or be able to forward or create new mail messages without it.


When the Agents node in the tree view navigation pane is selected the context pane displays the Machine Name, pasUnity version number, # of Accounts, # of Jobs, # of Work items, # of Hold items, Operating System, .NET Framework, and whether or not the Agent is enabled.


Creating Agents


Agents are created automatically the first time a service or user interface component is invoked on a machine in which the software has been correctly installed and configured. 


Agents may also be created in advance of being installed and configured by selecting and then right-clicking the Agents node in the tree view navigation pane and choose Add New Agent from the context menu.  You need to supply the host name (without DNS suffix) of the machine that the agent will be running on.  Creating an agent automatically launches the agent editor for further customization.  Manually creating agents is common in scenarios where you wish to pre-stage configurations before loading the pasUnity software on a host.


Editing Agents


To edit an agent, select the agent node in the tree view navigation pane to open the agent editor in the context pane.


Agents have the below attributes which can be modified through the editor.


Information tab:

Agent Machine Name: The host name (with DNS suffix) of the agent (this will appear in the navigation tree view pane).  If the agent machine specified does not EXACTLY match the name of the actual Windows host name, the agent will fail to pick up its configuration.

Processing Interval: The time that the agent will rest in between work cycles (processing jobs).  The default is 1 minute and should be adequate for most environments.

Collection Interval: The time that the agent will rest in between collection cycles (such as checking for mail).  The default is 1 minute and should be adequate for most environments.

Watcher Interval: The time that the agent will rest in between configuration cycles (such as checking changes to watchers).  The default is 5 minutes and should be adequate for most environments.

Processing Execution Threads: This is amount of jobs that the processing agent can execute simultaneously.  The minimum is 1 and the maximum is 256.  While setting a value larger than 1 will enable the execution of multiple jobs on the system, the default behavior of individual jobs is to run in serial unless job-level configuration allows for parallel execution.

Work Folder Path:  The location where temporary folders are created during job execution.  If no value is provided the default folder used will be the system-assigned temporary files folder.  During job execution a sub-folder will be created named for the work ID from the job queue.  Can be overridden by job-level configuration.

Enabled: By default, an agent is not enabled and must manually be enabled.  If an agent is not enabled it cannot automatically execute jobs, collect messages from mailbox servers, or monitor folders for changes.  Even if the jobs stored within an agent are enabled the agent itself must be enabled for the jobs to run automatically.  When an agent is not enabled jobs may be run manually from the local workstation only.

Diagnostics Mode: When enabled the pasUnity application and services will write additional detail to the Windows Event Viewer Application Log when processing jobs or executing service tasks.

SMTP tab:

Mail Account: 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 fail and job logs will not be delivered via email.  Only a full system administrator can configure this option.

FTP tab:

Enable FTP: Determines whether the pasUnity File Transfer Agent will listen for incoming FTP or FTPS connections.

FTP Port: The port to use to host the FTP services.  By default, this is usually port 21.  NOTE: If an existing FTP server is installed on the machine this setting will cause a conflict.

FTPS Certificate Find Type: The method to use in locating a certificate in the local machine store for securing FTP traffic.

FTPS Certificate Find Name: The certificate key used by the find method to detect the certificate.  If not provided, then FTP over SSL will not be available.

FTP Public Address (Optional):  A public IP to use when the FTP service is published through a firewall using network address translation (NAT).

Status tab:

Clicking inside this tab provides the current status of the pasUnity Services.

Key Value Pairs tab:

The Key Value Pairs tab is 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.

Key: The unique key name used to locate and/or manipulate values on the object scope where they are defined.  For example, a job can only have one key/value pair with the name Counter but the same name could be used on other jobs or on impeller of the same job for instance.  Key names are not case sensitive.  Key names are limited to 256 characters in length.  Key names cannot be changed once created without adding a new key/value pair and deleting the old value.

Value: The value associated with the unique Key.  The value has no maximum length.  You can store macro expressions in the key/value pairs but you will still need to parse them.

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.

Delete: Allows you to remove a key/value pair from the database.

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.


Deleting Agents


To remove an agent, select and then right-click the agent node in the tree view navigation pane and choose Delete... to remove the agent permanently from the database and the user interface.


Deleting an agent will also delete all jobs contained within that agent and the job history that has been stored.  It is not advised that agents be deleted if this information needs to be maintained.  In such cases it is recommended that the agent is disabled in the user interface and/or that the software is uninstalled from the host operating system of the agent.


Agent Favorites


Agent Favorites function in the same way as Favorites. Favorites are also available at the agent level to allow users with agent specific permissions to utilize this functionality.


Agent Event Viewer


Displays the Windows Event Viewer which contains monitoring and troubleshooting messages from pasUnity, windows, and other programs.  In order to use this functionality, the interactive user must have permissions within windows to access the Windows Event Log subsystem.  To access Windows Event Viewer data on a remote machine you must have permissions as previously described and the target machine must be enabled for remote administration.  NOTE: pasUnity specific details are stored in the Application log.


Agent Activities


Activity provides information on Exceptions, History, and Work for the Agent.  Clicking the column headers on any of the data grids will sort the grid.  Clicking twice changes the sort from ascending to descending.  Pressing F5 will refresh the contents of the grids from the database.  For information on system level Activity see Working with Activity.

Exceptions: A list of exceptions that have occurred on the Agent.  Exceptions are conditions that occur in the operation of pasUnity or the execution of jobs in which either an unexpected or undesirable condition has occurred.  To clear the list of exceptions for an Agent, right-click on the Exceptions node and select Clear Exceptions... from the context menu.  Double-clicking an exception from the top data grid will display a detailed exception stack trace in the lower pane (if such information exists).

History: The history provides a list of actions and outcomes from jobs executed on the Agent.  The top data grid shows system-level summaries with a single line for each job on the Agent.  The bottom data grid shows individual execution history (success and failure attempts).  Job logs are available for each line item by clicking on the Log button.

Work: The work queue displays jobs that are waiting to be processed, jobs that have failed, and jobs on hold on the Agent.  Once a job succeeds its record is moved to History.  If a job fails, its record is copied to History but the failed job remains in the work queue.  To permanently remove an item from the queue, highlight the row and press DELETE.  To review the past execution history of any work item in the queue click 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.  To manually execute queued work interactively you can press the Run button.  NOTE: In order to click the run button, the work item must already be in a hold status to ensure that the processing agent is not attempting to execute the work at the same time as the interactive user.


Copyright © 2024 pasUNITY, Inc.


Send comments on this topic.