Update: You may find a more current version of this article in the PS Corner Wiki.

Change Assistant was first released in PeopleTools 8.44 as part of PeopleSoft’s Total Ownership Experience program. It was meant to automate many of the tasks around applying maintenance, such as figuring out what needs to be applied, downloading the new maintenance programs, determining what order to apply the maintenance, checking prerequisites, applying the maintenance, and deploying flat files (like SQR’s, COBOL’s, Crystals) to file servers and NT and UNIX batch servers. Later versions of Change Assistant run compare reports and migrate the maintenance and customizations to your development/test/production environments.

Unfortunately the setup isn't very intuitive, and since I've been spending some quality time configuring Change Assistant lately I thought I'd add my two cents worth on how everything fits together.

Change Assistant Architecture
Automating so much of the maintenance tasks means that Change Assistant must know a lot about your environments. It needs to know where every file server, app server, process scheduler is and what machine they are on. It needs to know about your database, and what patches have been applied to it.

The system that gathers this information and makes it available to Change Assistant is called the PeopleSoft Environment Management (PSEM) Framework.

The PSEM framework has two important components: 1) The PSEM Agents which are set up on each of your PeopleSoft servers and crawl the disks looking for PeopleSoft installations, and 2) The PSEM Hub which gathers and reports on all of the environment information that the PSEM Agents send it.

The PSEM Agents listen on a pre-defined port for requests to shut down, perform a “re crawl” when the information gets out of date, or to accept a file from Change Assistant and move it to the correct directory. This is how Change Assistant is able to deploy new SQR’s and COBOL’s to your UNIX servers without resorting to FTP.

The PSEM Hub resides on the web server. It’s basically a servlet with an XML data repository. Look mom, no database!

The PSEMViewer is the component that extracts the information from the PSEMHub and puts it into an XML file so you can read it with a browser. It’s a nice tool if you’re wondering what (if anything) is in your PSEM Hub.

Change Assistant Setup
The biggest part about setting up Change Assistant is getting the PeopleSoft Environment Management Framework configured. I generally get this set up before I even install Change Assistant.

To start with, pick an environment that will serve as your PSEM Hub. I usually pick a Demo environment to play this role. Beyond that, there’s not a lot of PSEM Hub configuration you have to do at this time.
The PSEM Agent configuration is deceptively simple. Go to $PS_HOME/PSEMAgent/envmetadata/config and edit configuration.properties. What matters here is the hubURL (http://<yourservername>:<port>/PSEMHub/hub); the Agent Port (must be unique); and the drives to crawl.

So how many Agents do you need on a server? Well, it depends. If you have a Windows server and all of the PS_HOME directories are under one Base directory, you can probably get away with just one Agent process that crawls all of your PS_HOME directories. In that case, the windowsdrivestocrawl parameter just needs to include the Base directory that’s above all of the PeopleSoft Home directories, and you’re done.

On the other hand, if you have a UNIX server and all of the PS_HOME directories are owned by a different user, one Agent is going to get permission problems when it tries to crawl into directories it doesn’t own. In that case, you’ll have to set up a different PSEMAgent for each PS_HOME directory that you have. Each agent will need its own port number and the unixdrivestocrawl will be set to its PS_HOME.

Once you get the Agent(s) configured, start it with either StartAgent.cmd or StartAgent.sh. The first time I run an agent, I always issue the recrawl command so that it simply crawls the environment, identifies and verifies the web server/app server/process schedulers, and quits. That way if there are any weird errors I can see them immediately. For example:

$ StartAgent.sh recrawl
INFO main EMF_CATEGORY – Proceeding with matching for AppServer
INFO main EMF_CATEGORY – Proceeding with matching for prcsserver
INFO main EMF_CATEGORY – Proceeding with matching for Host
INFO main EMF_CATEGORY – Proceeding with matching for WebServer
INFO main EMF_CATEGORY - Diff: Hours 0 Minutes 0 Seconds 12

So far so good. It looks like the agent found my app server, process scheduler, web server, and it figured out it was running on a host. Now we need to start it up normally so that it will continue to run and communicate with the hub.

Here’s the UNIX command I use to run the agent in the background.
$ nohup StartAgent.sh &

I don’t have a good command to run the agent in the background on NT. If you have one, please share!

When all of the agents are running, enter your HubURL in a browser and verify that your agents are registered and they are in a Running state.

Are they running? Great. Now let’s configure and run the PSEMViewer just to make sure all of the information about your environments made it to the hub.

Configuring and Running PSEMViewer
PSEMViewer has its own configuration.properties file under $PS_HOME/PSEMViewer/envmetadata/config. It doesn’t really matter which PS_HOME you run this from.

Just like the PSEMAgent configuration, make sure you enter a valid hub URL and a unique port number. I don’t believe the DrivesToCrawl parameters are relevant for PSEMViewer.

Once configuration.properties is set, go to $PS_HOME/PSEMViewer and run GetEnvInfo.bat (or GetEnvInfo.sh for UNIX). This will contact the hub, download all of the XML data, and put it in an xml file called viewer.xml under $PS_HOME/PSEMViewer/envmetadata/data. There’s also a file called viewer.html in the same directory that formats the XML file. If you’re on Windows, simply double-click on viewer.html to see your data. If you’re on UNIX, move the two files to a web server directory or FTP them to your client and double-click on them. Then you can review your environment.

When you’re reviewing your environment, make sure that all of your environments are listed by name, that updates are listed under the Environment Updates tab, and hosts, file servers, app servers, process schedulers, and web servers all show up as expected. If not, go ahead and troubleshoot the problems before continuing.

A note about the GUID
The GUID is a really big alpha numeric random number that uniquely identifies a database. It’s stored on the PSOPTIONS table, and is set the first time you start a process scheduler or application server. If you clone your production database to create a new Dev or Test environment, you’ll want to reset the GUID to its previous value if possible. Otherwise the data in the hub will get out of date along with any data you’ve previously uploaded to PeopleSoft. If you can’t reset the GUID to its previous value, update the PSOPTIONS table and set the GUID to a space before you start the app server or process scheduler.

Configuring Change Assistant
Is everything working OK now? Great! Let’s install and configure Change Assistant.

First, run the simple setup program at %PS_HOME%\setup\PsCA\setup.exe. The install process isn’t too remarkable so I won’t waste your time on screen shots or explanation.

If you’re running multiple tools releases, you can run the version of Change Assistant that you prefer. An 8.47 change assistant works fine with an 8.46 environment.

Once installed, launch Change Assistant. When it comes up click on Tools > Options. The Change Assistant Options dialog box will appear.

Make sure the Apply Application Update radio box is selected. On the Change Assistant tab, you’ll specify the directories that Change Assistant will use.

I generally create a ChangeAssistant directory under my PS_HOME directory, and create a Download, Staging, and Output subdirectories. Then I enter them in this page.
Change Assistant Options
The Email and Web Services tabs are specific to your environment, so you’ll have to determine what goes there (if anything). On the Environment Management tab, enter the PSEMHub server name, and the PSEMHub server port in the spaces provided. Click Ping to make sure they work.

On the “Settings”, you’ll notice there is a “Drives to Crawl” field. Change assistant prefers to crawl the workstation that it resides on instead of asking you where things are installed. Be sure you let it crawl the drive that your database connectivity programs are installed – otherwise you’ll get a “Unable to find SQL query tool for the environment” when you try to apply your change packages. I generally let it crawl the PS_HOME directory too, although I’m probably just superstitious.
Change Assistant Options
Other Change Assistant Settings
Although I’ve never had to do this, according to the PeopleTools Installation and Upgrade guide the following firewall rules are required as well:
To use Enterprise Change Assistant, you must configure your firewall settings so that the firewall does not filter PeopleSoft domain and IP names.
Note. When setting trust rules or bypass rules on your proxy server, or in browser security, it is easier to maintain rules by domain or IP subnet.
The following features must be set to allow access for PeopleSoft Enterprise Change Assistant:

  • Domains: Allow access for the domains www.peoplesoft.com and update.peoplesoft.com. We recommend that you set domain rules to allow access to *.peoplesoft.com.

  • IP addresses: Allow access for the IP addresses and We recommend that you set IP rules at the subnet

  • FTP sites: Configure your firewall to allow inbound ftp when the request is not initiated on the same port.

Software update requests go to PeopleSoft Customer Connection on one port number, and the actual download comes back on a different ftp port number.
Change Assistant uses SSL to connect at all times, but when you log in to PeopleSoft Customer Connection or Update Gateway through a browser only the login page is SSL.

I hope this overview helps you get Change Assistant set up and working properly. As always, please leave a comment if you have any questions.
Written by :
Comments (13)Add Comment
Comment from Nachu
written by Nachu, May 03, 2006
Setting up Peoplesoft Change Assistant
Comment from Amr Malik
written by Amr Malik, May 21, 2006
Excellent article! I've been looking into using the PSEM framework for other purposes like actually managing the environment from one single console. Are you aware of any info regarding the internals and how the communication between the CA and the EMHub actually happens? Protocols, any API etc that they have made public?

Thanks for a very informative article!
Brent Martin
written by Brent Martin, May 22, 2006
That's an interesting question. Unfortunately I'm not aware of anything out of Oracle that documents the communication process. It looks as though communication between the Agents and EMHub occurs via XML over HTTP, so I might speculate that Change Assistant uses XML too. I'm not sure if Change Assistant contacts agents directly or if the EMHub brokers the conversation.

There's certainly no API that I'm aware of. It seems very closed and proprietary.
Comment from Dacco
written by Dacco, June 06, 2006
Thank you. This article helped me quite a bit.
Comment from Chris Hulsey
written by Chris Hulsey, July 09, 2006
You asked, "I don’t have a good command to run the agent in the background on NT. If you have one, please share!"

I'm not a PeopleSoft guru, but I'm about to try running the StartAgent.bat file as a scheduled task. After reading your article, yesterday I decided to try this. It appears to work at least on the level of the agent registering with the PSEMHub.

There are some settings I chose to ease administration.

1) Create two scheduled tasks one called PSEMAgentStart and PSEMAgentStop. (Each pointing to the appropriate StartAgent.bat and StopAgent.bat files and working directories).

2) Set each task to run as "System". Hint: don't try supplying a password, system is the computer account and it will handle password changes, etc. for you.

3) (optional) Remove the checkbox next End this task if it runs for more than 72 hours. This allows you to view the job as "running" on the server side, but is really more of an aesthetic than a real indicator of status. If you don't modify this property the task, after 72 hours the task will not show running in the Task Scheduler, but it will continue running the agent. Use "hubURL" from the article to view the status of the PSEMAgent.)

4) Right click the PSEMAgentStart task and choose "Run".

This was tried on Windows Server 2003 SP1 server, but I couldn't verify that CA actually works properly, as I don't know how to test CA client. Maybe someone will be kind enough to verify this works or doesn't work. As I indicated the agent runs and registers with the PSEMHub but beyond that I can't say for sure.

Maybe this will help someone.
Comment from Sunil Kowtal
written by Sunil Kowtal, July 20, 2006
In the Database Config Page, while setting up the Environment the Old PS_HOME is Disabled. Is there any setup to be done for this to be enabled.

Please Advise.

Comment from Mukesh
written by Mukesh, August 28, 2006
Very much sufficient with the purpose you prepared this for.

Thanks for your efforts.

Brent Martin
written by Brent Martin, January 10, 2007
There's a good thread on Yahoo groups http://tech.groups.yahoo.com/g...sage/45812 that makes some good points about Change Assistant.
written by Pryscila, November 22, 2007
Thanks to the author of this article.
It helped us a lot, after some days of hard work to find way Change Assistant wasn't working.
Change Assistant problem...
written by suman, June 24, 2008
Hi Brent,
I have one problem with Change assistant.In Options->upload environment, when I give the customer connection ID/PWD, I get the below error:
com.peoplesoft.pt.changeassistant.client.main.frmMain$49.actionPerformed(frmMain.java:3261) at javax.swing.AbstractButton.fireActionPerformed(Unknown Source) at javax.swing.AbstractButton$ForwardActionEvents.actionPerformed(Unknown Source) at javax.swing.DefaultButtonModel.fireActionPerformed(Unknown Source) at javax.swing.DefaultButtonModel.setPressed(Unknown Source) at javax.swing.AbstractButton.doClick(Unknown Source) at javax.swing.plaf.basic.BasicMenuItemUI.doClick(Unknown Source) at javax.swing.plaf.basic.BasicMenuItemUI$MouseInputHandler.mouseReleased(Unknown Source) at java.awt.Component.processMouseEvent(Unknown Source) at java.awt.Component.processEvent(Unknown Source) at java.awt.Container.processEvent(Unknown Source) at java.awt.Component.dispatchEventImpl(Unknown Source) at java.awt.Container.dispatchEventImpl(Unknown Source) at java.awt.Component.dispatchEvent(Unknown Source) at java.awt.LightweightDispatcher.retargetMouseEvent(Unknown Source) at java.awt.LightweightDispatcher.processMouseEvent(Unknown Source) at java.awt.LightweightDispatcher.dispatchEvent(Unknown Source) at java.awt.Container.dispatchEventImpl(Unknown Source) at java.awt.Window.dispatchEventImpl(Unknown Source) at java.awt.Component.dispatchEvent(Unknown Source) at java.awt.EventQueue.dispatchEvent(Unknown Source) at java.awt.EventDispatchThread.pumpOneEventForHierarchy(Unknown Source) at java.awt.EventDispatchThread.pumpEventsForHierarchy(Unknown Source) at java.awt.EventDispatchThread.pumpEvents(Unknown Source) at java.awt.EventDispatchThread.pumpEvents(Unknown Source) at java.awt.EventDispatchThread.run(Unknown Source
Not only for Upload Environment, but also for options->download Change Package, when I give the download path and the update ID and I click next and there it is asking for Customer ID/PWD, but when I give the login credentials it is giving me the above error. Please let me know what is causing this error.Thanks for your help.
written by varma, July 16, 2008
yes I have seen the article but it is meant meant for update ,i want Change assistant for application upgrade on remote server and what r the configurations we have to made to perform the upgrade from local machine.
Running batch file as service
written by Simon Huggins, September 28, 2009
Yes - I ended up using a ShareWare utility to wrap the agent into a service so it could be auto-started at windows launch without logging in, and also started/stopped at will. Since then, found a useful resource on this:
which gives a few different methods for doing this using standard NT tools.
written by Viswanadha, October 26, 2010
Hi Brent,
I have one problem with Change assistant,
We are having
One DB server (different mechine)
Two Web servers(both are different Machines):-
Here working fine

Application Server and Process Sheduler side:-
TWO Application and prcs Servers (one App Serevr and one prcs servers in one Machines and second also)?I am getting problem here when I am starting PSEMAgent.bat recrawl
i am getting below error:-

2010-10-22 01:03:21,947 main EMF_CATEGORY - Proceeding with matching for AppServer
2010-10-22 01:03:21,963 main EMF_CATEGORY - Detected an install for appserver at c:/UAT_HOME/UATHR//appserv/Search - unable to detect a configuration file. Ignoring this installation
2010-10-22 01:03:24,260 main EMF_CATEGORY - SFMAINT did not end normally
2010-10-22 01:03:24,260 main EMF_CATEGORY - C:UAT_HOMEUATHRPSEMAgent>set PS_SERVDIR=c:UAT_HOME/UATHR/appservUATHR


C:UAT_HOMEUATHRPSEMAgent>set EMF_XML_PATH=envmetadatadataemf_psae.xml

Error in sign on
Database Type: 6
Database Name: UATHR
Server Name:
OperID: PS
ConnectID: people
Process Instance: 0
Reason: Invalid user ID or password for database signon. (id=PS)
2010-10-22 01:03:24,275 main EMF_CATEGORY - See 'envmetadatadataemf_psae_error_UATHR.bat' to look at the script that could not complete.
2010-10-22 01:03:24,275 main EMF_CATEGORY - Detected an install for appserver at c:/UAT_HOME/UATHR//appserv/UATHR - unable to verify connecivity to a running database. Ignoring this installation
2010-10-22 01:03:24,275 main EMF_CATEGORY - Root Cause SFMAINT did not return a Success message.
Suggestions: make sure DB is started,check credentials in config file: c:/UAT_HOME/UATHR//appserv/UATHR/psappsrv.cfg

2010-10-22 01:03:24,275 main EMF_CATEGORY - Proceeding with matching for prcsserver
2010-10-22 01:03:26,557 main EMF_CATEGORY - Proceeding with matching for CLIENT
2010-10-22 01:03:26,588 main EMF_CATEGORY - Proceeding with matching for Host
2010-10-22 01:03:28,369 main EMF_CATEGORY - Diff: Hours 0 Minutes 0 Seconds 7

Note: our webservers ips are natted with other ips. so which ips are i want use here.

All are in windows only , Please help me on this

Write comment

security code
Write the displayed characters


Last Updated on Wednesday, 10 May 2006 19:34.