Wednesday, May 27, 2015

PeopleTools 8.54+ - Branding - Part 4A - Customizing DEFAULT_THEME_TANGERINE_ALT Theme

If you have been following my previous posts on Branding PeopleTools 8.54+ applications (Part 1, Part 2, Part 3), then you would know that all my examples so far uses a delivered theme called DEFAULT_THEME_TANGERINE to perform customizations.


There is no issue with using DEFAULT_THEME_TANGERINE. Whatever we learnt in my previous branding posts provides great value to understand how HTML, css and javascript work together and how the latest PeopleTools configuration helps with achieving branding requirements in a much more simplified fashion.

I have had several folks enquire about the DEFAULT_THEME_TANGERINE_ALT theme and how to customize it? Well, my answer is that it is exactly the same process as we did with the DEFAULT_THEME_TANGERINE theme.


You will notice that the theme is more or less the same as DEFAULT_THEME_TANGERINE. The only additions are the 'Add To' (drop down), the 'Notification' icon and the 'NavBar' icon.

In general with the advent of more recent PUM Images (HCM 9.2 PUM 12) and the associate delivered FLUID pages, it appears that DEFAULT_THEME_TANGERINE_ALT might be a better theme to use particularly when we get to a stage where we are ready to roll out some of the delivered FLUID pages.

With that said, I would like to experiment with customizing the DEFAULT_THEME_TANGERINE_ALT theme in this post - titled PART 4A. The reason I titled this post as Part 4A is because initially I only intend to provide the basic details to get started with DEFAULT_THEME_TANGERINE_ALT. As time permits, I would follow up this post with a Part 4B which would cover much more detailed customizations (as we have seen in Part 1, Part 2 and Part 3).

Note: At the time of writing this post, I am using HCM 9.2 PUM Image 12 - PeopleTools 8.54.08.


Navigation: Main Menu > PeopleTools > Portal > Branding > Assemble Themes


Click on the 'Save As' Button and save the theme with a custom name (e.g.: CSK_THEME_TANGERINE_ALT).

Step 2: Clone DEFAULT_HEADER_TANGERINE_ALT Header Definition

Navigation: Main Menu > PeopleTools > Portal > Branding > Define Headers and Footers


Click on the 'Save As' Button and save the header with a custom name (e.g.: CSK_HEADER_TANGERINE_ALT).

Step 3: Update custom theme (Step 1) to reference custom header (Step 2)

Navigation: Main Menu > PeopleTools > Portal > Branding > Assemble Themes


Update Home Page Header to CSK_HEADER_TANGERINE_ALT.

Step 4: Upload Custom Branding Objects (Images, Style Sheets, etc)

Navigation: Main Menu > PeopleTools > Portal > Branding > Branding Objects

Upload Logo Image:

Upload Style Sheet:

Style Sheet for reference:

Step 5: Update the custom header definition

Navigation: Main Menu > PeopleTools > Portal > Branding > Define Headers and Footers


Delete the 'pthdr2logoswan' leaf under the 'pthdr2container' folder.

Add a new leaf element under the 'pthdr2container' folder to reference the custom logo.

Step 6: Update Branding System Options to use Custom Theme and Style Sheet

Navigation: Main Menu > PeopleTools > Portal > Branding > Branding System Options

Update 'Default Branding Theme' to CSK_THEME_TANGERINE_ALT and add CSK_BRANDING_CSS under 'Addtional Style Sheet Objects'.

Test Changes:

Recommendations if you are experiencing caching issues.
  1. Clear local browser cache.
  2. Shutdown, purge and reboot the web server(s).

You can see that the logo has been updated to the custom image using the DEFAULT_THEME_TANGERINE_ALT theme.

Stay tuned for Part 4B - Customizing DEFAULT_THEME_TANGERINE_ALT Theme (continued) and Part 5 - Branding Fluid!

Friday, May 1, 2015

DTD (Document Type Definition) Validations During Message Transformations

While testing cXML Invoice service operations in a FSCM 9.2 application, I found some interesting information regarding DTD (Document Type Definition) validation of messages particularly when there are transformations.

CXML_INVOICE is a delivered service that allows third party systems to send invoice data using cXML protocol.

When I was testing the CXML_INVOICE.v1 (synchronous service operation) in a FSCM 9.2 environment (PeopleTools 8.54.07), the service operation was returning an error although there was no issues with XML message. If the same xml message was used to invoke the CXML_INVOICE.v1 service operation in a FSCM 9.1 (PeopleTools 8.50.10), the invoice was processed without any errors.

I enabled tracing at the integration gateway and also at the message transformation level to further troubleshoot this issue. This service operation CXML_INVOICE.v1 has a transformation on the inbound request:

I found that the xml message was getting wrapped in a CDATA section as follows:

Original Request:
<?xml version="1.0"?>
<cXML payloadID="TEST_INVOICE_123" timestamp="2015-03-27T06:19:25-05:00" xml:lang="en-US">

Request with CDATA wrapper:

<?xml version="1.0"?>
<?xml version="1.0"?>
<cXML payloadID="TEST_INVOICE_123" timestamp="2015-03-27T06:19:25-05:00" xml:lang="en-US">

Due to this mysterious CDATA wrapping, the message transformation failed because the CDATA section changed the entire structure of the xml causing the xsl to fail while transforming the data to the appropriate fields in the destination format.

After some research on My Oracle Support, it was interesting to find the reason for the CDATA wrapping behavior. It turns out that the CDATA wrapper was caused by DTD validation issues on the Application Server.

Notice, <!DOCTYPE cXML SYSTEM ""> in the original xml? This represents the Document Type Definition for the XML document. The application server would validate any inbound XML against the DTD if the DOCTYPE information is provided. The issue here is that the application server is unable to reach the location (possibly due to firewall issues) of the DTD for validation and therefore wrapped the inbound XML in a CDATA section.

On My Oracle Support there are a couple of documents which detail similar (not same) issues and provide some workaround options.

E-IB: Asynchronous Inbound Message With DTD Reference Was Wrapped As PsNonXML, Causing a Transformation Failure (Doc ID 1941030.1)
E-IB: DTD Validation Causes Time-Outs or Significant Delays During XML Processing (Doc ID 850271.1)

I used the workaround option to suppress DTD validation at the application server level using an Integration Broker property on the configuration file (psappsrv.cfg):

[Integration Broker]
; General settings for the Integration Broker
DTD Lookup=0

Once I made this change, the DTD validation was bypassed and subsequently the CDATA wrapper was also suppressed resulting in the transformation app engine to work as expected.

Note: This DTD Lookup IB configuration on the app server configuration file should not be confused with the ig.dtdLookup property on the IB gateway properties file.

I thought this was worth a blog post because I could not find much information on the DTD Lookup Integration Broker application server configuration in PeopleBooks (other than on My Oracle Support). Hope you find this useful!

The other workarounds that were suggested were:
  1. Remove the DTD URL from the XML documents. I don't think this is a viable option particularly in integrations that deal with third party systems where we cannot dictate the syntax and semantics.
  2. Place the DTD document that cannot be reached at its native location onto the same path on another HTTP server that is accessible to the app server (could be even the PIA web server). I found this to be a very interesting solution if we run into this issue and suppressing DTD validations is not an option. Please refer Doc ID 850271.1 for more details.