Thursday, June 21, 2012

Debugging Pages in Content Server 11g



More often than not, new developers working with Content Server are baffled as to “how” to find a given resource include to edit, or exactly what data sets are available on a given page.

There are some very useful flags that can be used to reveal a “behind the scenes” look at what is actually happening on a given page. 

This post deals exclusively with the 11g release.  There are other flags available that work in previous releases of the software, but most of them have been rolled up into a new flag (IsPageDebug), which will be covered later in this post.


  • IsJava
This variable can be set as either a flag on a page or as a parameter to a service call.  When set to “1”, it instructs the Content Sever to return the data in the databinder using the Content Server’s hda format as shown (using the service PING_SERVER for an example).  

http://myinstance/idcplg?IdcService=PING_SERVER&IsJava=1

Contrary to the official documentation, IsJava returns both “local” data, plus any result sets that are generated as a by-product of the INITIAL request.  






  • IsSoap
This variable can be set as either a flag on a page or as a parameter to a service call.  When set to “1”, it instructs the Content Sever to return the data in the databinder using a SOAP format as shown (using the service PING_SERVER for an example).

http://myinstance/idcplg?IdcService=PING_SERVER&IsSoap=1

Contrary to the official documentation, IsSoap returns both “local” data, plus any result sets that are generated as a by-product of the INITIAL request.





  • trace
This Idoc function enables logging a debug or trace message to the debug trace output. A message can also be output to the console or to the system logs.

This function can used when creating dynamichtml includes in components, or as statements in profiles and workflows in the various applets.  


The use of tracing messages, particularly in workflows, is a powerful way to debug problems where the standard debug isn’t clear.

The trace function takes two mandatory parameters and one optional parameter.




Option
Obligation
Notes
The message itself
Mandatory
The options are

  • Your special text string, or a string variable that has been accumulated. 
  • It can also be set to “#all” to output the entire contents of the databinder as it exists when the <$trace$> statement is called.
  • It can also be set to “#local” to output just the data in the local data section of the databinder as it exists when the <$trace$> statement is called.

The location where the message will be relayed.
Mandatory (the documentation says “optional” but the trace isn’t output or visible anywhere if this option isn’t set.)
The options are

  • “#console” - displays to a console or the system audit trace.
  • “#log” - logs a message in the HTML log files.
  • The name of a variable (such as “StatusMessage”). In that case, the message is appended to the current value.

Tracing section
Optional
This option is only valid when “#console” is selected as the second parameter.  To log a message strictly as a profile debugging tool, for example, this parameter would be set to “docprofile”.  A list of valid OOTB values can be found on the System Audit page, under the “Tracing Sections” portion of the page.

Using a section helps to tidy up the output, and makes reading the tracing messages much easier.



Examples of a trace statement:

The following example logs the string message to the system console, which is always logged:
                           <$trace("message", "#console")$>

The following example logs the string message to the system console in the pagecreation tracing section.
                           <$trace("message", "#console", "pagecreation")$>

The following example logs the string message to the HTML Content Server log file.
                           <$trace("message", "#log")$>

The following example dumps all local variables and their values to the system console.
                           <$trace("#local", "#console")$>

The following example dumps all local variables, result sets, and environment variables to the system console.
                           <$trace("#all", "#console")$>


The following example dumps all data to the variable “MyTraceDump”, which can then be displayed on the page. This is useful for HCSP developers who may not have the appropriate access rights to view the console or the logs.
                              
<$trace("#all", "MyTraceDump")$>
            <$MyTraceDump$>
As an example of using <$trace$> in an applet scenario, here is a profile rule with a trace statement, and the resulting output in the system audit trace in the “docprofile” section.





  • IsPageDebug
I am utterly shocked that this flag is not in the official 11g documentation!!  IsPageDebug in my opinion is the most powerful debugging tool available for a developer in 11g.  It exposes the same functionality as IsJava and ScriptDebugTrace in earlier versions, but adds the most powerful part - the full contents of the final page binder, and some javascript tracing as well.  

With IsJava and IsSoap, it was noted above that only the INITIAL binder is exposed.  However, many pages have either special functions or <$executeService$> calls during the course of the page rendering that add data to the binder.  This data is not available on the initial request, but IsPageDebug gets all of that data and makes it available at the click of a button.


Note that this parameter must be used with a page that has a template associated with it.  It won’t work with PING_SERVER, for example, but would work wonderfully with a checkin page or a search page.


http://myinstance/idcplg?IdcService=CHECKIN_NEW_FORM&IsPageDebug=1
Near the bottom right corner of the page, a small gray button is displayed.







Clicking the button expands a tray as depicted.






These buttons have mostly very useful data associated with them.


  1. idocscript trace -This option performs like <$ScriptDebugTrace=1$> performed in versions 10g and earlier.  It displays a list of every include statement evaluated to render a page, along with the file/filesystem path where that include statement is actually located.  Indentations in the code show the number of times the include statement has been overridden, which is really helpful when debugging issues with includes that contain “super” references.







request binder - This option shows the data available at the time of the page request.






response binder – This option is similar to IsJava, where the initial data binder for the service response is shown.  Clicking on a header like “Local Data” shows/hides the information associated with the section.






final page binder – this option exposes all of the result sets and local variables available AFTER the page has completed rendering.  This is way useful when trying to figure out “how” a data value was computed for display, since additional data can be loaded as part of the page build process.  It also shows any local data variables that may have been altered during page generation. Clicking on a header like “Local Data” shows/hides the information associated with the section.






javascript log – this option shows the javascript trace calculated on the page using the idc JavaScript trace functions.  This is not a substitute for a normal JavaScript debugger, and I haven’t found a really good use for the functionality – yet.






Hopefully this bit of information is useful to help find answers when you need to know “where” something is coming from.