Change Assistant

Written by Administrator

Saturday, 06 January 2007

Setting Up Change Assistant

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.

Running PSEMAgent as an NT service

If you're running EM Agents on Windows, it's nice to start them as services. Here's how:

1) Update the configuration.properties file as described above.

2) Open a Command window and navigate to PS_HOME\bin\client\winx86

3) Type: PSEMAgentService /install PS_HOME\PSEMAgent

4) Go to the Services panel and you'll see a new service called PeopleSoft Environment Management Agent-8.46.xx

5) If necessary, right click on the service and adjust the security (logon) parameters, etc.

6) To uninstall the service, do step #2 and then type: PSEMAgentService /uninstall

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%setupPsCAsetup.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.

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.

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 192.206.43.114 and 192.206.43.105. We recommend that you set IP rules at the subnet 192.206.43.0.
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.

Finally!

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.

Comments (26)

... : Jack

When I ping in CA options/environment management tab, I got the following,

Ping Environment Management Hub
Error: Environment Management Hub is not running

I am not sure how to check if env management hub is running. It's supposed to be running, as Hub agent is registered and running.

Thanks.

April 26, 2007

... : Brent Martin

To see if the PSEMHub is running, you can just enter the URL for it in the browser. For example -- http://:/PSEMHub/hub. It should come back with some kind of valid response code.

April 30, 2007

... : Jack

http://:/PSEMHub/hub says running state.

Now Hub is running, what else am I missing?

April 30, 2007

... : Brent Martin

All I can think of is to check the obvious stuff: Make sure the server name and port number are configured in Change Assistant, make sure you can reach the server from the machine that runs change assistant, make sure there aren't any proxy settings that might have been missed, etc.

Check Customer Connection for a solution, too. I know change assistant had problems in older tools releases. If that turns out to be the problem, you can usually upgrade the change assistant pieces without having to perform an entire PeopleTools upgrade.

May 03, 2007

Using CA for the first time !!!! : Mauricio Silvera

As it always happens, I am with just a short time in the project that I am working and I need to do update using the CA. I have problems that not like solving.
1 - Whenever it appears an error in the step execution ... since I can make follow independently with the execution the error ??
2 - Since I can make to accelerate the execution (template).
3 - Since I can do so that after executing "job" continue with the execution of the next one without the necessity to take part.

Thank you very much !!!

August 15, 2007

RE: Using CA for the first time !!! : Brent Martin

1) Errors in step execution: You can view the log file from change assistant. Review it and see if you need to worry about the errors. If not, right-click and mark the step as complete. If it's a problem you should fix it before moving to the next step.

2) Not sure what you're asking here, but it sounds like you want it to run faster. The best way is to deploy your own files -- don't let Change Assistant deploy files. Mark those steps as complete, find the files in the change package, and copy them to the correct directories yourself. Change Assistant is SLOW at moving files. A couple of other ways to make it run faster is to change the template and make steps run in parallel, and eliminate unnecessary steps. I don't recommend either approach -- some steps need to run sequentially and Oracle doesn't make it too clear which ones are needed for which products.

3) Sounds like you want to run in parallel, or apply bundles concurrently. Neither is a great idea unless you REALLY know what you're doing. If you're new to change assistant, just try to make it work like PeopleSoft intended for it to work. Once you're familiar with the process then you can experiment with the advanced functionality.

August 17, 2007

thanks : Mukesh

thanks a lot for this article.. very helpful

August 28, 2007

Need help!! : Shibani

Awesome article, I really appreciate it it's too helpful. have some question before I begin with setting up CA.
1. My Web/Batch server is on windows and apps server on unix, what I understand here is I have to make the configuration changes for PSEMagent/HUB in both $PS_HOME. Am I correct ?
2. The agent port mentioned in config.properties should be unique port and it is not my http port. Is this the port which helps the Hub/agent to interact ??
3. Regarding the drives to crawl, how can i setup unixdrive to crawl in my windows $PS_HOME as my application server is in unix.
4. Do i have to set GUID to ' ' and does it really make any difference if GUID is set to ' ' in psoptions.

Thanks

Shibani

September 13, 2007

RE: Need help : Brent Martin

1) Yes, you'll need to configure and start a PSEMAgent on every PeopleSoft server. They'll both need to point to the same PSEMHUB.

2) The agent port does need to be unique. The agent listens on that port for requests from change assistant (like to deploy files or to recrawl the PS directories to update configuration).

3) Your UNIX server will need to be running a PSEMAgent with it's own configuration. Your Windows server will need to have its own PSEMAgent running with its own configuration too. There's really no overlap between the two configuration files, so they can crawl whatever drives and directories are relevant for the server they're running on. There is supposed to be just one PSEMHub which will run on your web server. The two PSEMAgents will communicate with it.

4) Guid matters. Blank it out in PSOPTIONS, then bounce a process scheduler or app server. PS will populate it with a very ugly random code when it comes back up. It's a good idea to make sure PSOPTIONS contains a good database name and description for each database, otherwise it can get very confusing as to which database is which.

September 14, 2007

Need Help!! : Shibani

1. I have tried settingup CA, I have 2 $PS_HOME on the same host. I have modified the HUBURL and PSEMagent configuration files
when I try to start PSEMagents it points to HUBurl of 1st PS_HOME my actual hub url port is 8489, however it points to 8211 and says connection refused-
"Error main EMF_CATEGORY - Error while connecting to 'http://10.1.94.119:8211/psemhub/hub'"
Actually my huburl is 'http://10.1.94.119:8489/psemhub/hub'
I see my other PS_HOME on the same host has hub url of 'http://10.1.94.119:8211/psemhub/hub'
how do i configure it to point to the hub where i want it to be?

2. Also what are these and what info they give us "emf_psae.bat" "matchers.xml" "emf_xml_path" "SFMAINT" "Scrathpad" "Persistant Storage"

3. Also, what all info can i retrive and can be helpful through PSEMviewer.

regards

Shibani

September 18, 2007

RE: Need Help!! : Brent Martin

1) You should have just one Hub URL for ALL of your PSEMAgents regardless of which server or PS_HOME they run in. The Hub URL is configured in configuration.properties along with the drives to crawl. If you have that set right I don't know why it would try to connect elsewhere. You might try to configure just one PSEMAgent per server unless your different environments are owned by different users -- that could simplify things.

2) Those other directories provide persistent storage for what the crawl process finds. You may need to clear these out from time to time, especially if you refresh or move an environment. Customer connection has a nice solution about how to do that.

3) PSEMViewer basically generates an HTML file and an XML file that let's you see the contents of the PSEMHUB. You can see which environments are set up and which patches have been applied among other things.

September 20, 2007

Need Help!! : Shibani

Hi Brent,

Thanks a lot !!! it helped and im on the way to configure CA first time!!
Latest issue--

1. If my PS password contains Wild characters such as !@#*&# etc the agents running on my HP-Unix are not recognized by the Hub. This is only with Unix. I can create Passwords with wildcharacters with HP-UX users which means the shell is configured to take wild characters. sh shell

Regards

Shibani

September 26, 2007

RE: Passwords : Brent Martin

I'm not sure that makes sense to me at all. I don't recall specifying a username/password combo for the agent to communicate with the hub, and the agent logs on to the database using the password it finds in psprcs.cfg and psappsrv.cfg (which should work, because the app server and process scheduler start up with those passwords).

At one time I had problems getting app engines to run with users who had wildcards in their passwords, but that was back in the Tools 8.43 days.

You should take it up with GSC.

October 07, 2007

Need Help!! : Shibani

I mean the SFMAINT which runs does not detect the wild characters... PT 8.46

October 08, 2007

PS Admin : Marvin : http://www.kcmo.org

Here is the command to start your PSEM Agent in background on AIX/UNIX:

nohup ./StartAgent.sh > /dev/null &

October 09, 2007

Configuring Change Assistant: : Tanuja

When I issue a recrawl command, I get the following information

INFO main EMF_CATEGORY - Proceeding with matching for AppServer
INFO main EMF_CATEGORY - Detected an install for appserver at C://PT849/appserv/Search - unable to detect a configuration file. Ignoring this installation
INFO main EMF_CATEGORY - Proceeding with matching for prcsserver
INFO main EMF_CATEGORY - Proceeding with matching for CLIENT
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 1 Seconds -36

Any idea which configuration file it is looking out under ?./appserv/Search.

Thank you,
-Tanuja

February 21, 2008

PSEMHub is not running... : suman

Hi Brent,
This is an excellent info. But Im really poor in Change assisstant as I never worked on it.I have some small doubts.
1)In PSEMhub environmental details(configuration.properties) which url do we need to specify? Is it the web server name(ie machine name) or ome thing else likewise port number also?
2)While installing PIA (ie in mpinternet->setup) we specify the PSEMhub name and port details, what is that for?
3)As u specified in the doc above that how to chk whether PSEMhub is running or not, I have chked it by giving the url in the browser like this(http://my webservermachine name:webserver port number/PSEMHub/hub), but the result what it has given me is 404-Error.What does it mean?
4)If we need to start the Agents(ie StartAgent.bat) is it neccessary to chk whether appserver and proccess Scheduler are running?
5)And last one is, when I start my agent it is giving me this error:
"E:PT8.45PSEMAgent>StartAgent
ERROR main connection.cat - Error while connecting to server - retrying attempt
1
Error while connecting to server - retrying attempt 1"

Can you please answer my question?
Thanks for your help....

June 17, 2008

RE: PSEMHub is not running : Brent Martin

First, you need to make sure your hub is working. This is a component of your PeopleSoft web server. If your URL returns a 404, something didn't get installed right and you probably need to redeploy your application using MPINTERNET or PsMpPIAInstall.

If you get that working, I think the rest will fall into place.

The URL in configuration.properties should be the same URL that you copy/paste into your browser to make sure it works: http://my webservermachine name:webserver port number/PSEMHub/hub.

PSEMAgent will run whether or not your app server and process scheduler are running, but they need to be configured so they WILL start, otherwise PSEMAgent won't be able to use the information in the config files to connect to the application.

The port you specify in configuration.properties should be any open port. That's the port that the PSEMAgent will listen on for commands from the hub.

June 17, 2008

PESM Agent error... : suman

Hi Brent, Thanku for you r quick response.Now I see that my hub is running. But when I run PSEMagent Im getting like this:
"Sending pulse from 'com.peoplesoft.emf.peer:id=1" it is running like this for 20 mins. But, it is not giving any info. Can u let me know what does it mean...

June 18, 2008

RE: PSEM Agent Error : Brent Martin

Most of the time, all the PSEMAgent does is ping the hub. that's what this message means:

Sending pulse from 'com.peoplesoft.emf.peer:id=1

So congratulations, it's working!

When change assistant starts sending it commands (for instance to validate the configuration or deploy a file) you'll see different messages.

June 18, 2008

PeopleSoft DBA : SriSaro

Hi Brent,
Firstly, this is an excellent documentation. It explains each and every step clearly.I've been working with CA for some time and now is that I have a doubt and gosh it is bugging me so much. Ihave this CA set up for applying the ML6 (Cum), now when I select Apply Change Packages from the Tools menu, it takes drives me thru several windows, when I come to the window where it says, Select File Servers, I'm not able to see any details in the File Server: box. Here though i'm not seeing any details and hitting Next button , it takes me thru all the necessary windows and finally at the window, where it is Unzipping the Contents, it just remains at 0% and the window vanishes leaving the CA "Nothing Loaded". Kindly help me in this.

July 02, 2008

Extra agents according to the hub : Grant

The hub thinks I have more agents running than I actually do. CA tries to deploy to both, but since only one is running, the others fail.

Anyone have tips on convincing the hub that these are not real? We have already bounced the hub and cleared the cache.

July 22, 2008

RE: Extra agents according to the hub : Brent Martin

Once an agent connects, it will always be registered in the hub until you clear the hub's database. This goes beyond just clearing web server cache. Check out solution ID 200769631 on customer connection.

Basically the steps are to delete the files in the following directories under
PS_HOME/webserv/peoplesoft/applications/peoplesoft/PSEMHUB:

PSEMHUB/envmetadata/Scratchpad
PSEMHUB/envmetadata/PersistentStorage
PSEMHUB/envmetadata/transactions (if it exists)
PSEMHUB/envmetadata/data/*.* (files and directories. Don't delete the data directory itself)

July 23, 2008

RE: PeopleSoft DBA : Brent Martin

To make a PeopleSoft File Server show up, you'll need to start a PSEMAgent on your Windows server.

But a file server isn't required, so fixing that issue won't fix your other problem which I've never seen before. Review the staging & output directories, make sure you have permissions there and plenty of disk space, etc.

July 23, 2008

First time to CA : RajKeshava

Brent: Thanks for your detail documentation. I am in 8.45. I am getting an error message after I sign in to peoplesoft customer connection. It says "Error getting Content". I copied the detailed error description below

Detailed Error Description
Unable to signon to server.
Please contact your System Administrator.

Portal was requested to retrieve this URL:http://update.peoplesoft.com/psc/UGPRD/CUSTOMER/CPPROD/c/UPDATE_GATEWAY.UG_CC_UPDATES.GBL?PortalRegistryName=CUSTOMER&PortalServletURI=http://www.peoplesoft.com/psp/portprd/&PortalURI=http://www.peoplesoft.com/psc/portprd/&PortalHostNode=CUST&NoCrumbs=yes&

Portal attempted to access this URL:http://update.peoplesoft.com/psc/UGPRD/CUSTOMER/CPPROD/c/UPDATE_GATEWAY.UG_CC_UPDATES.GBL?PortalRegistryName=CUSTOMER&PortalServletURI=http://www.peoplesoft.com/psp/portprd/&PortalURI=http://www.peoplesoft.com/psc/portprd/&PortalHostNode=CUST&NoCrumbs=yes&

Thanks for your help

August 27, 2008

Re: "Ignoring this installation" : John C

Further to Tanuja's message (cannot find configuration file at the appserver stage) this case on CC refers; 201042885

The folder PS_HOME/appserv/Search is a new folder related to a new functionality appeared in PeopleTools 8.48: Configuring Verity to run as a separate process managed by the Application Server. Information about this can be found in PeopleBooks: System and Server Administration > Configuring Search and Building Search Indexes.

The Agent tries to retrieve the configuration file psappsrv.cfg for each application server domain, but since Search is not an application server domain, it doesn't find it and shows the above message. The message can be safely ignored, as the agent crawls all the other application server domains and sends the correct information to the Environment Management Hub.

October 14, 2008

Write comment