Customizing the IDM4.0 RBPM: Establishing a separate WAR file for customizations.

Rounding up all the steps required to customize an external theme.war file for the RBPM took a while, and because of that I thought it useful to pass on. The nice thing about this is that other than to copy your IDMProv.WAR file (or whatever you named it) out to a working directory, you never have to alter that main WAR file. You will make changes in another, custom file, and deploy it. If it doesn't work, delete the custom war file (which lives harmoniously, side by side with the "main" war file) and you're back at square one, functional one hopes, ready to try again.

What you will be doing:

• Creating a separate WAR file that contains nothing but the theme(s) you wish to customize.
• Modifying a number of config files within that custom war.
• Modifying ONE e-Directory attribute
• Deploying the custom WAR file to the same directory where your "Primary" war resides.

It SHOULD go without saying, but it doesn't: You are going to be replacing some files during the course of your work. Please, backup the file before you play with it, so that you can at least return the original to production (or, hopefully, the test environment where you are first experimenting with this!)

================================================================

Let us begin:

1. Copy entire deployed war file from /opt/novell/idm/jboss/server/<your deploy context>/deploy/<your deployed>.war to a working directory.

• Extract the contents of the file using "jar xvf <your deployed>.war . You will have to have JAVA executables in your path, or, from your working directory, issue a command like this to reference a working JDK:
  1. /opt/novell/jdk1.6.0_20/bin/jar xvf <your deployed>.war
     
     We'll reuse a lot of commands, so the up arrow will be your friend later.
• This will extract the entire contents of your deployed IDM war file in your working directory.
  1. There are MANY folders… you only care about 2 of them… (but we'll get there.)
• Within your "working" directory, Create a folder (Mine, I call "custom"), and
• Within that create two folders: "WEB-INF" and "resource"
• Back at the root of your working directory, copy the "resource\themes" directory and its contents into your "custom\resource\themes" directory.
  1. By default, IDM4.0 comes with only two themes, "BlueGloss" and "Neptune", so you will find those folders beneath your custom folder structure.
• RENAME the theme folders… say, "MyBlueGloss" and "MyNeptune"… You will be modifying the files in the next step to replace all references to "Neptune" with "MyNeptune".
• In the "\custom\WEB-INF" folder, create a file called "web.xml" with the following content<?xml version="1.0" encoding='UTF-8"?>
  <web-app>
  <display-name>myCustomThem</display-name>
  </web-app>
• So, to be clear you should have the following structure built:
  

  CUSTOM --
                 WEB-INF ---
                           web.xml
                 resource ---
                          themes ---
                                     MyBlueGloss---(and contents below it)
                                     MyNeptune --- (and contents below it)
  								   

  You may keep as many custom themes in your custom .WAR file as you like. This example has 2.
• Follow the other customization instructions in the RBPM documentation, specifically step 5 of the section "Creating a Custom Theme"
  1. http://www.novell.com/documentation/idmrbpm37/agpro/?page=/documentation/idmrbpm37/agpro/data/b6iiw3v.html#b6ij5tuSearch down and complete all relevant parts of STEP 5 of "Creating a Custom Theme."
     (Basically replacing references to "BlueGloss" with "MyCustomTheme" (or whatever)
     There are a bunch of edits. Take it slow and be sure you get them all.)
• REMEMBER: If you copied more than one "themes" folder, you'll have to repeat these steps within each of the themes you customize.
• CRITICAL: watch out when editing the "theme.xml"file. Some of the references to "Neptune" are part of paths to .jpg or .png photo files. You (for now) want to leave THEM alone. Alter only references that are about the "Theme" file… not to any "image" paths.

  You may ultimately do more of the things you find on this documentation page, but as far as simply getting a custom theme to work, let's keep moving.

After getting all of the files modified and corralled in your "custom" folder structure, you're ready to "jar" them up into a custom theme "war" file.

• FROM WITHIN THE ROOT of YOUR CUSTOM folder, issue the following command. (hit the up arrow to bring back your previous "jar" command, then modify it)

  /opt/novell/jdk1.6.0_20/bin/jar cvf MyCustomThemes.war *

  This basically says, "Roll up everything in the "custom" directory and pack it into a war file called "MyCustomThemes.war" (name it as you like.) (There are spaces between "jar" and "cvf", and before the asterisk (*) ).

  After issuing the command, you will see a new file appear alongside your WEB-INF and resource folders: "MyCustomThemes.war" You will deploy that in the last step, to the same directory where your "main" war lives.

• Now, for the kicker, before finally deploying the file: the one piece so completely hidden and secret that it is only discussed in the darkest back rooms of the Novell Forums.
  1. In "iManager," browse down to your UserApplication Driver, then go deeper into AppConfig, AppDefs, and on to the "Configuration" object.
• Right click it and choose "Modify Object"
• On the "other" tab you will double-click "XML-DATA"
  
  
  Click to view.
• In the box that appears, select everything (CTRL-A) and copy it out to a text editor (CTRL-C, then paste with (CTRL-V)
  
  Click to view.
• You will see a basic XML file, with a lot of entries for "Property" You will add one new property entry, anywhere amongst the other "property" entries, making sure to keep the tags properly sequenced. Add this:

      <property>
          <key>com.novell.rbpm.themes.list</key>
          <value>MyCustomThemes</value>
      </property>
  	
  	

  NOTE: The <value> is the NAME of your WAR file, without the extension. It is NOT the name of any of your custom themes that might be embedded in said .war file. (except by coincidence, perhaps)
• Cut the modified text file and paste it BACK INTO the XML Data field and save your changes.
• Finally, back in your custom folder on the server: Copy your custom theme .WAR file to the deploy directory where you first copied your "main" war file from. Usually something like this does the trick:

  From your custom folder: cp MyCustomThemes.war /opt/novell/idm/jboss/server/<your deploy context>/deploy/

• Flush the cache on your UserApplication, and return to the Theme Administration page. You should see your new custom themes.