Re-Customising (Customizing) Web after an Upgrade
Posted: Tue Nov 04, 2008 9:25 pm
Yesterday afternoon I installed 9.1 SP4 (replacing 9.1 SP3) as our web server. (Interestingly, for reasons best known to itself, Iboglix still hasn't put SP4 on the downloads page; you can still only get it from the FTP server.) The upgrade package itself ran flawlessly and easily (after I manually shut down all TM1 services), except for one little thing… it of course blew away all of the Web customisations that I'd put in.
I therefore thought that I'd post my own checklist of "stuff that you need to hack or change to customise Web" (or "customize TM1 Web", if you happen to be doing a search for that spelling) to provide some one stop shopping for these tips in future.
Some of these have been mentioned by either myself or others in past posts, but I don't recall seeing a single list before. (Where I recall seeing other people having posted this information, I give them an acknowledgement below; if I don't, it doesn't mean that no-one else has posted it, just that either I didn't see the post, or the post was after one that I'd made about it.)
File Location
Most of the files relating to TM1 Web are stored in the path C:\Inetpub\wwwroot unless you've changed that install path. And I oh so very much recommend that you don't unless you happen to be the type of person who enjoys complicating your life with trouble.
The key folder within that path is named TM1Web.
The 9.1 SP4 upgrade (and I'd guess this is true of all upgrades) will make a copy of that folder called TM1Web.1 (or presumably .2, etc if there's already a .1 folder, though I haven't checked that).
This is important because you may need to fish some files out of that folder, but I'll come back to that.
Customising The Login Page
The first thing that you may want to customise is your login page. Although that can be done manually, it's easier to use the TM1 Customiser (Customizer) application which allows you to change the main image, the banner, the swoosh grey line and the vertical line. Even the colour scheme if you're feeling adventurous. Note that you need to run this directly from a local drive on the server (not a networked share, even if it POINTS to a local drive), otherwise you'll get all kinds of arcane and pointless messages. (Tips hat to Adam Buckle for that information.) Before you upgrade, make a note of where you have stored the images that you already use for your login page so that you can punch them straight back in to the Customiser.
(This presupposes that you can FIND the Customizer application anywhere; I can't find it on the Cognos site. It used to be on the late and largely unlameted AOD site, which has closed down. Though it may be possible that a PM to one of the users who already has it could cause a copy to fall into your hands. Unofficially, of course.)
This tool won't FULLY customise the login page, however. There will still be a piece of text showing a Cognos copyright statement at the bottom right of the page. If you want to get rid of that (not to deny Cognos their legal rights, just because it looks blanking ugly over the graphic that we use), you can find the text in the file C:\Inetpub\wwwroot\TM1Web\TM1WebLogin.aspx
Modify the COPYRIGHT TEXT ONLY (this includes deleting it if you don't want any text at all appearing at the bottom right of the login page), but do not make any other modifications unless you are very, VERY comfortable with the syntax of .aspx documents.
(There's a version number shown in the left footer that you can get rid of as well. This isn't hard coded but is instead the dynamic expression <%=lblVersion%>. You can get rid of that as well if you want, though I prefer to leave it in.)
Customising Headers and Dialogs
If you want your own company name to appear in dialogs and the like (instead of "Cognos Web"), do a search for any .aspx documents in C:\Inetpub\wwwroot\TM1Web\ which contain "Cognos Web" in them, then modify them in Notepad. (If it's an upgrade, you may have already done that in the old .aspx files. In theory you could just copy the old files across but I so very much DON'T recommend it; it's possible that Iboglix changed some of the other coding of the pages, in which case you may cause yourself some pain. Better to spend the 5 minutes or so updating the new .aspx files.)
The first time I did that I kept a copy of the unmodified .aspx files, but that's not really necessary. It's up to you.
The Web.Config File
Now let's turn to modifications of the web.config file (C:\Inetpub\wwwroot\TM1Web\Web.config)
The Analyze / EV Link
The first thing I need to get rid of is the Analyze link which leads to Executive Viewer if you use it, or a promo for EV if you don't. If you don't use EV, you'll probably want to get rid of it as well. I replace it with a link called Corporate which points to my company's web site.
Look for the following code, and modify accordingly:
The text Corporate will replace "Analyze", the Description will replace the tool tip text that appears when you hover over the link, and the rest should be self-explanatory. (As I recall, it was Matt Goff who found that one and posted about it in the old Forum before I did.)
Stopping Users From Browsing Views
Next, we have to turn off the ability of our users to see views... something which SHOULD be customisable on a user by user basis but ooooh no, we have to have this as a GLOBAL option. Great. It's still possible to put views in as Applications, of course, but generally this is for people who don't want to have to bother with learning how to slice data and for whom Web will be deployed as essentially a presentation tool only.
Anyway, if you need to do that, find the following block in the .config file and change the "Y" to an "N" as shown.
Old Code:
New Code:
Hiding The Admin Host
Next, the Admin Host. Unless you're running multiple Admin Hosts (which we aren't), there's no point inflicting an extra entry on your poor long suffering users. Just enter the admin host server name between the quote marks as shown.
Note that this will remove the Admin Host text box from the login page completely, so only do it if you're sure that they'll NEVER need to change it.
Custom Help Files
Finally, the help file. Senior management did not like the standard Iboglix help file; the instructions in it meant nothing to them. I therefore wrote my own web based help file, specific to our deployment of Web, in Adobe RoboHelp. (And I say, without any commercial connection to or remuneration from Adobe, that when it comes to writing Windows help files RoboHelp is Da Business. It's not perfect (and the HTML editor is FAR less than perfect; I work in the Word editor mostly), but it's still a choice piece of software.) The help file I generated was a web based help one, in line with the original Iboglix files.
If you also write your own help file, you should put the files in C:\Inetpub\wwwroot\TM1Web\Help. (I put my files in a sub-folder of that, leaving the existing Iboglix ones in place. Technically you could probably put them on another path, but I preferred not to.)
If you're upgrading, those files will have moved to the C:\Inetpub\wwwroot\TM1Web.1 folder with the other files from your earlier version. You'll therefore need to copy your custom help folder back over into the new C:\Inetpub\wwwroot\TM1Web path.
This time you'll need to modify one of the javascript files; specifically C:\Inetpub\wwwroot\TM1Web\scripts\tm1webtop.js
The part that you need to modify is:
which becomes:
Happy modding...
I therefore thought that I'd post my own checklist of "stuff that you need to hack or change to customise Web" (or "customize TM1 Web", if you happen to be doing a search for that spelling) to provide some one stop shopping for these tips in future.
Some of these have been mentioned by either myself or others in past posts, but I don't recall seeing a single list before. (Where I recall seeing other people having posted this information, I give them an acknowledgement below; if I don't, it doesn't mean that no-one else has posted it, just that either I didn't see the post, or the post was after one that I'd made about it.)
File Location
Most of the files relating to TM1 Web are stored in the path C:\Inetpub\wwwroot unless you've changed that install path. And I oh so very much recommend that you don't unless you happen to be the type of person who enjoys complicating your life with trouble.
The key folder within that path is named TM1Web.
The 9.1 SP4 upgrade (and I'd guess this is true of all upgrades) will make a copy of that folder called TM1Web.1 (or presumably .2, etc if there's already a .1 folder, though I haven't checked that).
This is important because you may need to fish some files out of that folder, but I'll come back to that.
Customising The Login Page
The first thing that you may want to customise is your login page. Although that can be done manually, it's easier to use the TM1 Customiser (Customizer) application which allows you to change the main image, the banner, the swoosh grey line and the vertical line. Even the colour scheme if you're feeling adventurous. Note that you need to run this directly from a local drive on the server (not a networked share, even if it POINTS to a local drive), otherwise you'll get all kinds of arcane and pointless messages. (Tips hat to Adam Buckle for that information.) Before you upgrade, make a note of where you have stored the images that you already use for your login page so that you can punch them straight back in to the Customiser.
(This presupposes that you can FIND the Customizer application anywhere; I can't find it on the Cognos site. It used to be on the late and largely unlameted AOD site, which has closed down. Though it may be possible that a PM to one of the users who already has it could cause a copy to fall into your hands. Unofficially, of course.)
This tool won't FULLY customise the login page, however. There will still be a piece of text showing a Cognos copyright statement at the bottom right of the page. If you want to get rid of that (not to deny Cognos their legal rights, just because it looks blanking ugly over the graphic that we use), you can find the text in the file C:\Inetpub\wwwroot\TM1Web\TM1WebLogin.aspx
Modify the COPYRIGHT TEXT ONLY (this includes deleting it if you don't want any text at all appearing at the bottom right of the login page), but do not make any other modifications unless you are very, VERY comfortable with the syntax of .aspx documents.
(There's a version number shown in the left footer that you can get rid of as well. This isn't hard coded but is instead the dynamic expression <%=lblVersion%>. You can get rid of that as well if you want, though I prefer to leave it in.)
Customising Headers and Dialogs
If you want your own company name to appear in dialogs and the like (instead of "Cognos Web"), do a search for any .aspx documents in C:\Inetpub\wwwroot\TM1Web\ which contain "Cognos Web" in them, then modify them in Notepad. (If it's an upgrade, you may have already done that in the old .aspx files. In theory you could just copy the old files across but I so very much DON'T recommend it; it's possible that Iboglix changed some of the other coding of the pages, in which case you may cause yourself some pain. Better to spend the 5 minutes or so updating the new .aspx files.)
The first time I did that I kept a copy of the unmodified .aspx files, but that's not really necessary. It's up to you.
The Web.Config File
Now let's turn to modifications of the web.config file (C:\Inetpub\wwwroot\TM1Web\Web.config)
The Analyze / EV Link
The first thing I need to get rid of is the Analyze link which leads to Executive Viewer if you use it, or a promo for EV if you don't. If you don't use EV, you'll probably want to get rid of it as well. I replace it with a link called Corporate which points to my company's web site.
Look for the following code, and modify accordingly:
Code: Select all
<!-- Sets an external link to Executive Viewer. -->
<add key="EVLink" value="Corporate;Description=Launch the MyCompany Web Site;Url=http://www.mycompany.com.au;" />Stopping Users From Browsing Views
Next, we have to turn off the ability of our users to see views... something which SHOULD be customisable on a user by user basis but ooooh no, we have to have this as a GLOBAL option. Great. It's still possible to put views in as Applications, of course, but generally this is for people who don't want to have to bother with learning how to slice data and for whom Web will be deployed as essentially a presentation tool only.
Anyway, if you need to do that, find the following block in the .config file and change the "Y" to an "N" as shown.
Old Code:
Code: Select all
<!-- NavTreeDisplayServerView: Y/N - Whether to display "Server View" node in navigation tree -->
<add key="NavTreeDisplayServerView" value="Y" />Code: Select all
<!-- NavTreeDisplayServerView: Y/N - Whether to display "Server View" node in navigation tree -->
<add key="NavTreeDisplayServerView" value="N" />Next, the Admin Host. Unless you're running multiple Admin Hosts (which we aren't), there's no point inflicting an extra entry on your poor long suffering users. Just enter the admin host server name between the quote marks as shown.
Code: Select all
<!-- If set, users will not be asked to enter Admin Host during login. -->
<add key="AdminHostName" value="YourTM1AdminHostServer" />Custom Help Files
Finally, the help file. Senior management did not like the standard Iboglix help file; the instructions in it meant nothing to them. I therefore wrote my own web based help file, specific to our deployment of Web, in Adobe RoboHelp. (And I say, without any commercial connection to or remuneration from Adobe, that when it comes to writing Windows help files RoboHelp is Da Business. It's not perfect (and the HTML editor is FAR less than perfect; I work in the Word editor mostly), but it's still a choice piece of software.) The help file I generated was a web based help one, in line with the original Iboglix files.
If you also write your own help file, you should put the files in C:\Inetpub\wwwroot\TM1Web\Help. (I put my files in a sub-folder of that, leaving the existing Iboglix ones in place. Technically you could probably put them on another path, but I preferred not to.)
If you're upgrading, those files will have moved to the C:\Inetpub\wwwroot\TM1Web.1 folder with the other files from your earlier version. You'll therefore need to copy your custom help folder back over into the new C:\Inetpub\wwwroot\TM1Web path.
This time you'll need to modify one of the javascript files; specifically C:\Inetpub\wwwroot\TM1Web\scripts\tm1webtop.js
The part that you need to modify is:
Code: Select all
function ShowHelp()
{
window.open("Help/tm1_web_client_help.htm", "tm1webhelp");
}Code: Select all
function ShowHelp()
{
window.open("Help/YourFolder/YourHelpFileHomePage.htm", "tm1webhelp");
}