Running an Environment Management Agent
This section discusses how to:
Run an agent.
Start an agent automatically in Windows.
Before you run an Environment Management agent, you must ensure that it's properly configured in the agent's configuration.properties file.
Starting the Agent
At a command prompt, navigate to PS_HOME\PSEMAgent.
Use one of these scripts to start the Environment Management agent:
On Microsoft Windows, run PS_HOME\PSEMAgent\StartAgent.bat.
Note: If you want the agent to start automatically when the machine starts, use the Microsoft Windows service that's delivered as part of PeopleTools. Or, you can add the script to the startup applications.
On UNIX, run PS_HOME/PSEMAgent/StartAgent.sh.
Note: If you want the Environment Management agent to start automatically on UNIX when the machine starts, add StartAgent.sh to the login/boot scripts.
The first time an agent starts, it crawls the machine to locate PeopleSoft elements on that machine. The results of searching the hard disk are saved in the PS_AGENT_HOME\envmetadata\data\search-results.xml file.
Note: When starting an agent
manually from the command prompt or from a script, the command prompt
will continue to stay open, and it is normal to see the output of
the periodic heartbeat events ("sending pulse") in the command prompt
as the agent communicates with the hub. By default these "pulses"
are every 10 seconds, except when environment information is being
uploaded to the hub. You can configure the agent to run in the background
using the provided Windows service, and on UNIX by using the
These options are documented in other sections of this PeopleBook.
Note: Only one Environment Management agent can be started per machine. If an agent is already started, you may receive error messages indicating that the agent cannot be started because there is already one running on the machine.
Starting the Agent on a Secure PS_HOME
On Microsoft Windows:
Create a new shortcut from the desktop (right-click, New, Shortcut).
In the Type the location of the item enter:
<PS_HOME>\PSEMAgent\StartAgent.bat -u :<domainname>\<username>
c:\ptinstalls\pt851\PSEMAgent\StartAgent.bat -u :bigcompany.com\tsawyer
Where the user specified has write access to PS_HOME.
Note: When you run <PS_HOME>\PSEMAgent\StartAgent.bat -u :<domainname>\<username>, the %TEMP% directory is used. Both the user that runs the command and the "runas" user need write/execute access to the %TEMP% directory.
Click Next, and enter a name for the shortcut.
Use this shortcut to start the agent.
Log in as the user who has write access to the PS_HOME.
Stopping the Agent
Use one of these scripts to stop the Environment Management agent:
On Microsoft Windows, run PS_HOME\PSEMAgent\StopAgent.bat.
On UNIX, run PS_HOME/PSEMAgent/StopAgent.sh.
If you install new software components, the running Environment Management agent doesn't automatically detect them. This is because, to improve performance, the agent doesn't crawl every time it starts up. Instead it crawls only if the search-results.xml file does not exist.
You can force a recrawl and make the new components manageable by reissuing the StartAgent command with the recrawl option:
Open a new command line window.
Change directories to PS_HOME\PSEMAgent.
Issue the following command:
This forces a recrawl and creates a new search-results.xml file. If an agent is already running, it publishes the results to the hub.
If the running Environment Management agent is connected to the hub constantly, the recrawl interval occurs every 24 hours by default. If the agent has not been connected to the hub for a few days, the hub requests the agent to recrawl when the agent contacts the hub the next time.
Note: Recrawling includes revalidating.
Note: The recrawl process assumes the Environment Management agent is running. If it is not running, you may see error messages in the output. It is recommended that before running a recrawl, you make sure the agent is running.
If the Environment Management agent does not recognize any of the installed components, the search-results.xml file may not exist or may contain only an entry for Host. The problem may be that the agent needs to have permission to read directories as well as execute programs. Grant these permission for the agent. Also check whether the agent has permission to create a file on the local file system. Finally, check whether the disk is full. The agent might have no disk space to create a search-results.xml file.
If the hub is not running, you may receive the following error messages in the agent log or console:
Broken connection - attempting to reconnect.
RemoteException while connecting to server - retrying attempt 1.
RemoteException while connecting to server - retrying attempt 2.
RemoteException while connecting to server - retrying attempt 3.
Once the Environment Management hub is back up, the agent will successfully connect. There's no need to stop and restart the agent.
Note: If you are performing a recrawl, you don't need to separately revalidate.
Command-Line Arguments for the Agent
You can run these command-line arguments with the startAgent.bat (or startAgent.sh) script.
Returns the version of the agent.
Version:8.45 Build Number: 109
Shuts down a previous instance of the agent if it is running.
If the agent does not exist:
If the agent exists:
Prints the URL of the hub with which the agent is configured to communicate.
Validates the current set of managed components that have been discovered from the last crawling by the agent.
Not applicable (NA)
Recrawls the hard disk to detect new configurations. Recrawls the detected database environments to update database information. The current search-results.xml file is backed up.
Note: Recrawling includes revalidating.
Returns true if an agent is already running and false if an agent is not already running.
Removes the peer and all its registered components from the hub.
Removal Completed- PeerID 2 has been removed.
Removal Failed- PeerID 2 could not be removed from the hub.
Use the UNIX
with the StartAgent.sh script to start an agent automatically and
run in the background. This enables you to avoid having a command
prompt open at all times showing the constant heartbeat of the agent.
You can specify an output file to store heartbeat information.
nohup ./StartAgent.sh > agent_output.log &
You can set an Environment Management agent to start automatically when your Environment Management machine boots and run in the background. This enables you to avoid having a command prompt open at all times showing the constant heartbeat of the agent.
For this option, use the PSEMAgent Windows service that's delivered as part of PeopleTools.
Installing the PSEMAgent Service
You install the PSEMAgent service from a command prompt. Copies of the install program are located in two places:
To install the PSEMAgent service:
At a command prompt, change to either location of the install program.
Enter the following command:
PSEMAgentService /install PS_HOME\PSEMAgent
Where PS_HOME is the PeopleTools installed location.
The PSEMAgent service is now installed, but not started. It's configured by default to start automatically when the system boots, and to log on using the local system account. You can start it manually, or wait for the next reboot.
Note: The PSEMAgent service is configured to start as an automatic service, by default. However, the Hub must be running prior to the PSEMAgent service attempting to start, or the PSEMAgent service will not start successfully. It is recommended to set the PSEMAgent service to manual start in the Windows Services interface. Then, to start the PSEMAgent service, start it manually from the Services interface.
Starting the PSEMAgent Service
You can start the PSEMAgent service from a command prompt, or from the Windows Services control panel. The name of the service follows this convention: PeopleSoft Environment Management Agent-<release>.
To start the PSEMAgent service from a command prompt, use the NET START command. For example:
NET START "PeopleSoft Environment Management Agent-8.50"
To start the PSEMAgent service from the Windows Services control panel:
Open the Windows Control Panel, then double-click Administrative Tools, then Services.
In the Services control panel, right-click the PeopleSoft Environment Management Agent entry and select Start.
Stopping the PSEMAgent Service
You can stop the PSEMAgent service from a command prompt, or from the Windows Services control panel.
To stop the PSEMAgent service from a command prompt, use the NET STOP command. For example:
NET STOP "PeopleSoft Environment Management Agent-8.50"
To stop the PSEMAgent service from the Windows Services control panel:
Open the Windows control panel, then double-click Administrative Tools, then Services.
In the Services control panel, right-click the PeopleSoft Environment Management Agent entry and select Stop.
Uninstalling the PSEMAgent Service
You uninstall the PSEMAgent service from a command prompt.
To uninstall the PSEMAgent service:
At a command prompt, change to either location of the uninstall program.
Copies of the uninstall program are located in two places:
Enter the following command:
PSEMAgentService determines if the service is currently started, and automatically stops it before completing the uninstall operation. You'll see messages reporting on the status of the operation.
Note: If the service is currently stopped, you'll see an error message indicating that it can't be stopped. Regardless of this, the uninstall operation completes normally.