Custom Coach Overrides and Single-Sign-On

At my client, we have defined and built a business process using IBM BPM 7.5.1, which includes coaches, and we display these coaches within our existing IBM Portal based solution.

There were a few challenges along the way in order to integrate BPM and Portal, including configuration of Single Sign On (SSO), and none of which actually caused real pain, apart from one little, almost trivial issue, which took us quite some time and effort to sort out.

We want the BPM coaches to look and feel just like all other Portal content, so we lifted the relevant CSS classes from the Portal solution and use them to override the default coach CSS. Of course that was fun to do, there was a lot of Firebug involved and eventually things were looking rather good, to the point where our coaches are now indistinguishable from any other portal content in the system.

But once we successfully completed the SSO configuration we lost the custom look and feel, which was puzzling, because we could see the customised coaches when testing the BPD from Process Designer, we could see them when we were running them on the playback server, but they reverted to the default coach appearance when going through Portal.

So eventually I had to roll up my sleeves, pump some Bassdrive into my skull and really dig in.

I fired up Fiddler, started monitoring HTTP traffic from my browser and discovered that my requests for the custom_coach.css file resulted in a 302 redirecting to the teamworks login page.

Interesting, SSO worked fine for everything but the CSS file. Teamworks did not see that particular request as coming from a trusted source.

And then I saw it. All other requests were to, but the CSS one was to http://bpmhost:appserverport/teamworks/csspath

When Teamworks serves the Coach, it sends to the browser links to a bunch of things, including the CSS file in question, and this link was being composed using the machine hostname, without the fully qualified domain, and with its app server port, rather than the web server port.

There are two problems with this. One is the port as it was forcing the browser to talk directly to a particular app server in the cluster, when we really want it to go through IHS, though this wasn’t breaking things. The other one is the non qualified hostname. This did break stuff.

The way SSO seems to work, when the browser receives the LTPA cookie, it is allowed to propagate it to servers in the same domain. So, after logging in to it was successfully requesting coach content to but failing to retrieve the CSS file from bpmhost.

It turns out that there is a configuration file in the system folder for the bpm installation called 99Local.xml that controls such things. It defines URL prefixes for quite a number of moving parts, including Teamworks web resources, so a global replace of all hostnames to include the domain, and port to point at the web server, followed by a server restart did the trick.




About Gabriel Telerman
Occupation: IBM SOA-BPM Consultant. Profession: Guitar Hero

12 Responses to Custom Coach Overrides and Single-Sign-On

  1. Todor Mollov says:

    Thanks for sharing this.
    How do you show the coaches in the portlets. Do you use Business Space widgets both for the task list and for showing the coach for a task?
    Did you have to use a lot of custom html in the coaches or you did everything in an external CSS?

  2. Gabriel Telerman says:

    Hi Todor, for the look and feel everything is in an external CSS and we applied it globally at the Process App Settings level in PD.

    As for Portal integration we simply display the entire BPM related content in its own tab. So we ‘integrate at the glass’ rather than full and proper. No BS Widgets.

    The task list is a coach service showing the list of tasks based on our own query criteria and a bunch of other coaches off the list to perform whichever action to the selected task.

    We use custom html but only to embed script chunks to control visibility and behaviour of page controls.

    Hope this answers your question.

    • Todor Mollov says:

      Hi Gabriel,
      That’s exactly what I’m interested in.
      You say you display the entire BPM related content in its own tab. I assume you have two portlets one for the task list and another to show the coaches in. Effectively you have an iFrame portlet which you point at the BPM URL of the task list coach service. There, the coach has multiple entries for each task and for each task you have a URL.
      Do you open the URL in the same portlet, or you open the task coach in a popup window or you have come up with some clever mechanics of sending the URL to another iFrame portlet which will open the task?
      Also can you communicate with other portlets i.e. send data from a coach to another portlet on the same page?


  3. Gabriel Telerman says:

    Everything happens in the same portlet/tab.

    You are right, the portlet points at the task list which is a coach service exposed as URL, so it’s a startable service.

    There is a repeating table in this coach showing the task attributes we choose to display, then, in the Presentation properties of one of the attributes (the case number) we make it a link by adding the following custom html:


    where tw.local.taskURL is pre-initialised as:
    tw.local.taskURL = “/teamworks/process.lsw?zWorkflowState=1&zTaskId=”;

    and the index ‘i’ is the built-in way of using list variables to populate repeating tables.

    So, when the user clicks on this link in any row in the task list s/he is taken to the activity for the task, which happens to be a coach that loads in the same portlet (_self).

    The user can come back to the task list because the task coach has a link back to the task list.

    No clever mechanics I’m afraid :-/

    • Todor Mollov says:

      I’m researching this integration again.
      On the task coach when you have a link back to the task list coach … How do you show it?
      If you have a task and it is finished, the default message ” Service compled” is shown and you cannot customise this default page i.e. cannot add URLs?
      Thanks, Todor

      • Gabriel Telerman says:

        Hey Todor,

        Going back to the task list is relatively simple:
        You can have a Back button creating a flow to a coach service where this coach just has a custom HTML block with

        <script type="text/javascript">
        document.location.href = "<#=tw.local.taskURL#>";

        where taskURL will be a link to your task list, as in


        Telling Portal that whichever task we are in has finished is a bit dirty. (OK, downright ugly)

        What we did is, just before the task end state we put in our own coach displaying whatever we want and yet another custom HTML chunk with:

        <script type="text/javascript" src=<#=tw.system.model.findManagedFileByPath("jquery-1.4.2.min.js" , TWManagedFile.Types.Web).url #> > </script>
        <script type="text/javascript" src=<#=tw.system.model.findManagedFileByPath("" , TWManagedFile. Types.Web).url #> > </script>
        <script type="text/javascript" src=<#=tw.system.model.findManagedFileByPath("json2.js" ,  TWManagedFile.Types.Web).url #> > </script>
        <script type="text/javascript">
                var serviceFinished = new Object();
                serviceFinished.command = 'coachServiceFinished';
                $.postMessage(JSON.stringify(serviceFinished), '*', window.parent);

        So when the user clicks the coach button we post a message to portal to tell them we are done. Portal has to implement the callback and do whatever to the BPM iframe. We had to use Jquery postmessage because of browser version. You might be lucky enough to be able to dispense with that (IE9 now supports native window.postMessage).

        There’s a lot of dirty hacks, cross origin workarounds, sso ltpa token sharing, session expiration headaches, task ownership issues…

        Also, the default ‘Service has finished’ is nothing but a JSP in one of the product war files. If you can get away with replacing it fine. Our environment people weren’t too happy with that step every time they build an environment or apply a product patch…

        Hope this helps!

      • Todor Mollov says:


        This helps a lot thanks!
        If you have to do this integration again, portal 8 and BPM 8.0.1 which approach would you take?
        – custom portlets
        – business space
        – web clipping

      • Gabriel Telerman says:

        That’s a difficult question and I’m the wrong person to answer, because I’d probably end up doing the same again, simply because I have charted these waters now! I have neither recipes to go by nor battle scars on the other approaches. And once the business have something working and the project is deemed a ‘success’ nobody will risk doing the next one using a ‘better’ way :-/

  4. Mike says:

    Where does SSO fit in? What SSO implementation was deployed?

    • Gabriel Telerman says:

      Hi Mike, haven’t been involved in the SSO implementation itself, but I know that all requests have to be made to hosts in the same domain for it to work, and because the CSS request did not have the fully qualified name, bpm did not service it, so, from a browser experience we were just silently not seeing the customised look and feel.

  5. Vignesh says:

    I was searching for something else but accidentally stumbled upon this post. I wish I read this two days back. We were having a similar problem but the root cause was that we configured HTTPS instead of the default HTTP. Similar port reference problem occurred.

    Very well written Gabriel. Thank you :)

  6. saket says:

    Hi Gabriel, Nice and useful article. I am right now stuck in one another problem at the moment. I have a multiselect repeating table with 2 columns. Product Name and Attributes. These details are filled corresponding to the Service you select. So, for example for Internet I have 3 products under it and the corresponding attributes of each one. Now the problem starts – I have a requirement from the client that if the user selects Ethernet then the ProductA under it should come as read only and “Checked” when the data populates in the table. i.e. the user will have to buy that particular product if he selects Ethernet service. Mandate for Ethernet. Other products should be populated normally with a check box. The user can then decide whether he wants other products or not by clicking on the checkbox.

    Please help me solve this issue. Thanks in Advance.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: