<$ practice makes perfect $>

ValidateContent and CollapseFCKelements components updated

2011-09-29T21:41:00.000-04:00

ValidateContent
A visitor pointed out the java class wasn't even packaged. Many apologies to those who downloaded and couldn't get it to work.

CollapseFCKelements
Now compatible with Site Studio 10gR4 9.0.0.718

Download both on my Docs & Files page

Fixing ssUrlPrefix for HTTPS (vs HTTP)

2011-06-30T18:32:00.003-04:00

If you host a site studio site using HTTPS, you may notice some links being incorrectly generated by server-side scripts (ie. ssGetServerRelativePath); specifically, the home page "URL Directory Name" being used as a prefix. This results in broken links, but are otherwise valid when viewed via HTTP.

The reason for this is because the value of ssUrlPrefix changes when using HTTPS (most likely "/home/") vs. HTTP ("/"). Unless you want your homepage to be, for example, http://stellentpmp.blogspot.com/home instead of http://stellentpmp.blogspot.com, ssUrlPrefix should be consistent throughout the site.

So how do we fix this?

The answer is simpler than you think. Login to the content server and navigate to Administration » Site Studio Administration » Manage Web Site Addresses. Typically, you have one web site address for each web site hosted on the content server, but you need to add a second address with the SSL port for each web site that uses HTTPS, like so:

Web Site: [select your web site]
Address: [your web site address]:[SSL port]

For example:
Web Site: stellentpmp (stellentpmp.blogspot.com)
Address: stellentpmp.blogspot.com:443

If you're interested in why you need to do this and/or how I figured this out, read on. Otherwise, thank you for reading :)

ValidateContent Component

2011-05-31T19:15:00.029-04:00

One thing that Oracle UCM doesn't provide out of the box is a way to prevent content, based on file type and size, from being checked in. I never got around to implementing a solution in the past, but after seeing a constant need for it on the OTN Forums (1, 2, etc), I finally decided to set aside some time to create a component to do just that.

My ValidateContent component uses the validateStandard filter, has its own tracing section, and can also check for empty/blank metadata values. You can find it on my Docs & Files page; just be sure to look at readme.txt for help on configuring it for your needs.

Any suggestions and/or bugs, please leave a comment. Good luck.

mdaw Directory Explained!

2011-05-18T17:15:00.004-04:00

The mdaw folders are created based on the 'dispersion rule' of the your FileStore (Administration » Providers » FileStore Info » Edit FileStore » Edit [default] Storage Rule). Basically this rule helps separate your content by storing them into multiple directories.

The default rule is $dRevClassID[-9:-6:0:b]/$dRevClassID[-6:-3:0:b], which basically takes two 3-digit substrings of dRevClassID and encodes it into a Base64 string.

The first substring will always map to '000' (the 9th, 8th, and 7th digit) until you reach 1 million records. The second substring will map to the next three digits (the 6th, 5th, and 4th digits, or the 100-thousands', 10-thousands', thousands' place) of your dRevClassID. This will be always be '000' until you reach 1000 records, in which case it will be '001'. Once you hit 2000, it will be '002', 3000 is '003', etc.

If you encode the substring, '000' becomes 'MDAw', '001' becomes 'MDAx', '002' becomes 'MDAy', etc. Therefore, if you have < 1000 records, the dispersion rule will use '000' and '000' to store the content, mapping it to MDAw/MDAw. Once you hit 1000 records, it will store them in MDAw/MDAx. Once you hit 1 million records, it will start using '001' as the first directory. Thus, the 1,000,000th document will be stored in MDAx/MDAw. Even though they have capital letters, I imagine Oracle just takes the value and performs a .toLowerCase() transformation on it to give the infamous mdaw.

So you can say that, by default, your documents are stored in groups of 1000 and bigger groups of a million.

Naturally, you can create your own dispersion rule (say only groups of 10,000 documents), or even get rid of it completely. If you "go back" to the 10gR3 vault/weblayout structure, you'll need to edit the "Vault Path" of your Storage Rule or edit the [install directory]/data/providers/[filestore]/provider.hda directly, and remove the $dispersion$ variable. However, you'll need to go the second route if you want to change the Web-viewable Path because Oracle made that read-only (for some strange reason) on the Store Rule page.

You can read a little bit more about this in section 4.3.5.5.3 Limiting the Number Files in a Directory of the System Administrator's Guide.

Good luck.

Collapse empty/blank FCKEditor elements

2011-05-13T13:18:00.001-04:00

By default, a contribution region has all its elements expanded when it loads. Depending on the number of elements you have, this can take up valuable screen real estate or even cause excessive scrolling. It can be particularly frustrating if an element is rarely used and takes up half the screen, such as a dynamiclist element that returns zero results.

If you use FCKEditor, however, you're in luck. Simply download and enable my CollapseFCKElements component (found on my Docs & Files page), and all empty/blank and optional elements are automatically collapsed upon load!

Ideally, I would like to have component configuration variables that allow you to control when an element becomes collapsed (ie. CollapseTextElement=true). However, I'm not sure how to pass them to or read them from the javascript files. Any suggestions (or requests), please leave a comment or email me.

Consider workflow to release site studio content

2011-04-19T18:46:00.011-04:00

With Site Studio contributor, every Save/Update is checked in as a new revision that is then immediately released by the content server. While I think this is status quo for many instances, I urge you to reconsider this out-of-the-box functionality on a case-by-case basis.

Why? One word: drafting

When users edit content, they usually make countless changes before it's actually ready to be released [to the public]. Whether they're taking a break, thinking about what to write next, or just getting a head start, users want to be able to save a draft before it's published. I wouldn't blog if I couldn't draft a posting.

If you're asking how this is any different from the default functionality, consider the following drawbacks:

Multiple revisions are unnecessarily created
As stated earlier, every save you make is checked in as a new revision. Let's assume you took a week to add a new section to a document and saved it 25 times. That would create 25 separate revisions; 24 more than you would probably ever need. Seriously, would you ever need a copy of those 24 changes?
The last published version is not easily identified for rollback
Since all revisions are released by default, there is no unique identifier that lets you know which of those revisions is the last published version vs a draft. In the previous example, you would have to go through 25 revisions before finding it. Who wants to do that?
You are artificially creating a new "revision status"
Since there is no distinction between drafted and published content, you are creating an "in draft" revision status. As far as the content server is concerned, however, all 25 revisions in the example are released; even though they shouldn't be.
Disk space is wasted
As the number of stored revisions goes up, disk space loss goes up.
Drafted content could wind up being published
Content is considered publishable when its revision status is "Released". In the example, any of the 24 previous draft revisions could be published.

I've seen issue #5 usually [improperly] handled with a custom "xPublish" metadata field, but it still doesn't fully address items #1 thru #4. Wouldn't it be great if there was a solution that not only eliminates the need for another metadata field, but encapsulates "draft mode" within a single revision; thereby resolving all the issues above? No, keeping the contributor window open is not a viable option :)

Enter: workflow

The strategy is simple: if you give contributors the ability to edit and approve their own content, drafting becomes compartmentalized within workflow and publishing becomes more controlled. Here's how:

1. Open Workflow Admin and create a token named Current_Author with the following user:

<$wfAddUser(#active.dDocAuthor, "user")$>

2. Create a Criteria workflow that matches the content you want to allow drafting

3. Add a step named DraftAndEdit, select the "Users can review and edit (replace) the current revision" radio button

4. Add the token from #1 to the users assigned to this step.

5. Optional: add the following idoc to the Entry step:

<$wfSet("wfJumpEntryNotifyOff", "1")$>

6. Enable the workflow

The key is step #3, where it gives the author the ability to make an infinite number of edits while the content is in "review". It isn't until the author approves the piece of content that the workflow exits, releasing the content and making it available for consumption.

How this solves the issues above:

Multiple revisions are unnecessarily created
When a document is in workflow, all edits and changes are encapsulated within a single revision.
The last published version is not easily identified for rollback
With workflow, every content revision is in a published state. Therefore, the last published version is simply the previous revision.
You are artificially creating a new "revision status"
The "in draft" state has been replaced with workflow (revision status of "Review"). The "Released" revision status is now used as it was intended.
Disk space is wasted
Every save/update is temporarily stored, instead of checked in as a new revision. As the number of revisions goes down, disk space loss goes down.
Drafted content could wind up being published
Workflow content is never published because its revision status is not "Released". Therefore, every revision is considered "publishable"; you will never have to worry about drafted (un-publishable) content being released.

Welcome to a cleaner, more efficient content server.

Good luck.

PS. One downside to this is that it may seem a little counter-intuitive to approve your own content. It must always be kept in mind, however, that you are merely finalizing your draft edits. Alternatively, you can create a "Finalize Edits" or "Publish" menu choice as described in Kyle's post to make it more logical.

Create your own Tracing Section

2011-03-07T18:11:00.003-05:00

If you've written custom java filters, idoc scripts, or services, you've probably added some basic logging using SystemUtils.trace("system", "log message");. However, wouldn't it be nice to separate your logs by creating your own UCM tracing section (GET_SYSTEM_AUDIT_INFO)? It's easier than you think.

In your component definition (.hda) file, add the following:

... to the ResourceDefinition table

resource
resources/custom_resources.htm
customTraceSections
500

... to the MergeRules table:

customTraceSections
IdcTracingSections
itsSection
1

... to the resource file defined above (ie. custom_resources.htm):

<@table customTraceSections@>
<table border="1"><caption>Custom Tracing Sections</caption>
<tr>
 <td>itsSection</td>
 <td>itsDescription</td>
 <td>itsDefaultEnabled</td>
</tr>
<tr>
 <td>customTraceName</td>
 <td>trace custom component</td>
 <td>false</td>
</tr>
</table>
<@end@>

Then change either of the following to suit your needs:

"customTraceName" to the name you want to use for your tracing section. This is what appears within the tracing section dropdown list.
itsDefaultEnabled to "true" if you want your tracing section to be active/turned on after restarting the content server.

At this point, your tracing section is set up and ready to be used by your java code (after restart).

First, be sure to include the SystemUtils class:

import intradoc.common.SystemUtils;

Then simply add tracing like this:

SystemUtils.trace("customTraceName", "Thanks stellentpmp!");

or like this if you want to utilize "Full Verbose Tracing":

if (SystemUtils.m_verbose)
{
SystemUtils.trace("customTraceName", "Thanks stellentpmp for everything!");
}

Good luck.

How "secure" is your Site Studio site?

2011-02-18T21:19:00.005-05:00

NOTE: This only applies to sites hosted directly off of Site Studio; meaning, not published via the Site Studio Publishing Utility (SSPU).

If you don't know how content is secured within Site Studio, expand this:

In my experience, many places have a poorly designed security and metadata model (not to mention an un-normalized one). As a result, I have seen many implementations give the anonymous user (R)ead access to ALL security groups and the #all account. In my opinion, there is no chance that 100% of your content is "web ready" and insensitive by nature. Is it possible? Sure, but I'm more likely to be the Redskins' quarterback next year, so why expose your web site and content server unnecessarily?

What's my point in all this?

What if I were to say that I could obtain copies of your entire fragment libraries, along with your layout pages, and also know the names and email addresses of those who edited them?

How?

Anyone who has worked with Oracle UCM knows of idc services. Well, what's preventing them from executing a service call off YOUR content server as the anonymous user? Many services only need (R)ead access to be called, which the anonymous user has. Take a look at these snapshots off Oracle.com:

If you're not careful, your fragments and layout pages can also be at risk of being downloaded - there is such a thing as proprietary code, right? And no, setting "Allow get copy for user with read privilege" to false will NOT suffice.

There may also be instances when the anonymous user requires (W)rite access to the content server, such as calling the SUBMIT_HTML_FORM service. Allowing this kind of functionality means you have to be aware of anonymous users calling idc services that require (W)rite access! Sorry, no screenshot :)

So, are there ways to prevent all this? Absolutely, but it first falls on your security and metadata model. Afterwards, you can look to install the ExtranetLook component and also redirect unauthorized service calls. I've even implemented my own adhoc security solution, but I don't know what overhead there would be on high-traffic sites.

After reading this, you can argue that this is a "flaw" with the content server itself. That's true, but your content server probably isn't sitting within a DMZ and subjected to outside attack if you're not using Site Studio. So, how "secure" is your Site Studio site?

I certainly can't be the only one to have thought of this... right?

Credential Maps - Tips & Tricks

2011-02-17T19:58:00.001-05:00

NOTE: This post assumes you authenticate externally with Active Directory (AD), have a basic understanding of its schema and Security Groups (ADSGs), already have a working LDAP provider, and have a separate LDAP role/account prefix for each of your UCM instances.

Chances are that if you authenticate externally, you've tested your luck with credential maps. I say "luck" because deciphering its syntax for the first time is akin to waiting in line to use the restroom: frustratingly painful. In a nutshell, credential maps are a part of the ProxyConnections8 component that allow you to link ADSGs (and their members) to Oracle UCM roles and/or accounts.

If you need a credential map that can link everything one-to-one:

ADSG

Role/Account

admin
  »
admin

contributor
  »
contributor

intern
  »
intern

Corporate_R
  »
Corporate(R)

ImageLibrary_RW
  »
ImageLibrary(RW)

use the following:

#Maps all roles
|#all|, %%

#Maps all accounts
@|#all|, @%%

Note: the #all term does not refer to an ADSG named #all; it is a reserved keyword to signify ALL ADSGs listed within the LDAP Role/Account Prefix OU.

As powerful as the above map is, it has one fundamental flaw:

It doesn't map the #none and #all accounts

This issue revolves around naming limitations; namely, an ADSG name cannot contain certain special characters, including the # symbol. Therefore, the only way to resolve this issue is to use a valid name, such as:

#Maps all roles
|#all|, %%

#Maps all accounts to their respective account
@|#all|, @%%

#Maps #all and #none account
@|all|, @#all
@|none|, @#none

One caveat to credential maps is that its mappings do not override one another. That is, mappings listed at the bottom do not overwrite the ones above it; so any role or account can be mapped multiple times. Therefore, assigning a user to the "all" ADSG in the above mapping will result in a double mapping: "all" and "#all". To prevent this, the credential map needs to ignore the "all" (and "none") ADSG, like so:

#Maps all roles
|#all|, %%

#Maps all accounts to their respective account
@|#all -all -none|, @%%

#Maps #all and #none account
@|all|, @#all
@|none|, @#none

Single, Shared Active Directory

Another problem with the above mappings is that they assume you have a separate AD for each Oracle UCM instance; which explains why it can be reused. If you have an environment that uses a single, shared Active Directory, however, how would you assign someone to be an admin for development, but only a contributor for production? Even if you have a separate LDAP role/account prefix for each UCM instance, you cannot have two ADSGs with the same name (ie. "admin") because they must be globally unique.

In order to handle this, you need to map each instance individually. The simplest way is to add a prefix to each ADSG (I recommend the UCM instance name), followed by a dash (-): "dev-admin" and "prod-admin". Doing so, however, would require similarly named UCM roles. While there is nothing wrong with that, it would be ideal if we could map them both to something of our choosing; namely, just "admin". In fact, you already explicitly mapped to the #all and #none accounts in the above mappings, so we can employ the same idea.

Therefore, you can map an individual UCM instance:

ADSG

Role/Account

dev-admin
  »
admin

dev-contributor
  »
contributor

dev-intern
  »
intern

dev-Corporate_R
  »
Corporate(R)

dev-ImageLibrary_RW
  »
ImageLibrary(RW)

dev-all
  »
#all

dev-none
  »
#none

by using this credential map:

#Maps all roles
|#all|,      %%[4]

#Maps all accounts except the dev-all and dev-none accounts
@|#all -dev-all -dev-none|,       @%%[4]

#Maps the "dev-all" ADSG to the #all account
@|dev-all|,       @#all

#Maps the "dev-none" ADSG to the #none account
@|dev-none|,     @#none

Note: The number in between the brackets ([ ]) is the number of characters to ignore before mapping the rest of the string (marked by %%). Make sure to change this accordingly.

In the off chance that you are using the same LDAP Role/Account prefix for all your UCM instances, you will need to change your credential map to the following:

#Maps all "dev-" roles
|dev-|,      %%[4]

#Maps all "dev-" accounts
@|dev-|,       @%%[4]

#Maps the "dev-all" ADSG to the #all account
@|special/dev-all|,      @#all

#Maps the "dev-none" ADSG to the #none account
@|special/dev-none|, @#none

Things to note:

1. The "dev-none" and "dev-all" accounts are in a "special" OU group because we don't want them mapped twice. You can certainly change the name to something that won't be affected by the first mapping, @|dev-|, @%%[4], but I chose to keep the same naming structure for consistency sake.

2. I chose the name "special" for the separate OU group, but it can be any qualified name.

I've hopefully covered everything; if not, here's one last, but very helpful tip:

While the 'at' symbol (@) indicates accounts and no 'at' symbol indicates roles, there is nothing that prevents you from mapping them with each other. In other words, you can map roles to accounts, and vice versa.

For instance, if you have a "prod-intern" role that should always be given (R)ead access to the Corporate account, you would have the following:

|prod-intern|, @Corporate(R)

By using this approach, you would never need to manually assign users to the "prod-Corporate_R" ADSG; or even create one for that matter. You can't even do that with the User Admin Applet. Think of the possibilities!

I chose to highlight this because I don't think many people realize it.

Good luck!

Build a smarter workflow approval step

2011-02-12T10:06:00.001-05:00

Even though workflow has its uses, it's pretty rough around the edges. One thing that should be built in is recognition of its own approvers; meaning, it should be smart enough to skip any step if the dDocAuthor is one of the assigned approvers of the step. Why should you needlessly approve your own content if you're one of its approvers?

Bypass this redundant workflow step by adding this token to it: +Expand

<$executeService("GET_ALIASES")$>
<$skipStep=0$>
<$aliasToUse="[AliasName]"$>
<$if rsExists("AliasUserMap")$>
 <$loop AliasUserMap$>
 <$if strEquals(AliasUserMap.dAlias, aliasToUse)$>
 <$if strEquals(AliasUserMap.dUserName, #active.dDocAuthor)$>
 <$skipStep=1$>
 <$break$>
 <$endif$>
 <$endif$>
 <$endloop$>
 <$if isFalse(skipStep)$>
 <$exec rsFirst("AliasUserMap")$>
 <$loop AliasUserMap$>
 <$if strEquals(AliasUserMap.dAlias, aliasToUse)$>
 <$if not strEquals(AliasUserMap.dUserName, #active.dDocAuthor)$>
 <$wfAddUser(AliasUserMap.dUserName, "user")$>
 <$endif$>
 <$endif$>
 <$endloop$>
 <$endif$>
<$endif$>

Just remember to change [AliasName] to an actual alias that exists in your system.

Good luck.

Custom Property: null vs blank

2011-02-05T11:33:00.009-05:00

To determine if a custom property is null (ie. does not exist) vs. blank, use the following code snippet:

[custom property exists]

[custom property doesn't exist]

Note: It is a misprint in both the 10gR3 and 11g Site Studio Technical Reference Guides when it says the SS_GET_ALL_CUSTOM_NODE_PROP_DEFS service returns a ResultSet named "CustomNodePropertyDefs"; it is actually "CustomNodePropDefs". In fact, my blog has the only reference to "CustomNodePropDefs" on the internet...seriously. Also, SS_GET_ALL_CUSTOM_NODE_PROP_DEFS requires write access to call it so make sure to handle that accordingly.

Good luck.

What website section is this?

2011-01-27T20:09:00.005-05:00

As you know, the Web Site Section metadata field (xWebsiteSection) is in the format: siteId:nodeId

That's not particularly helpful when using the default Headline View on search results pages of the content server. Display the section label instead by adding this dynamic HTML resource:

<@dynamichtml slim_table_cell_text@>
<$if ColumnProperties.id like "xWebsiteSection"$>
<$"<$theSection = eval(#active.xWebsiteSection)$>"$>
<$"<$siteID = strSubstring(theSection, 0, strIndexOf(theSection, \":\"))$>"$>
<$"<$sectionID = strSubstring(theSection, strIndexOf(theSection, \":\")+1)$>"$>
<$"<$if strLength(theSection) > 0$>"$>
<$"<$ssGetWebsiteName(siteID) & \" : \" & ssGetNodeLabel(siteID,sectionID)$>"$>
<$"<$endif$>"$>
<$else$>
<$include super.slim_table_cell_text$>
<$endif$>
<@end@>

Good luck.

What's my exact dDocAccount access?

2011-01-26T18:00:00.001-05:00

It's often helpful to know what access rights (RWDA) you have to account(s). By default, "My Profile" only displays the account(s) that you have at least (R)ead access to. A simple change to the user_info.htm template should clear things up (putting this in a custom component is a best practice, but won't be discussed here):

Around line 150, you will find:

<td colspan=2 nowrap><$lc("wwAccounts")$></td>
<td colspan=2><$if UserAccounts$><$UserAccounts$>
<$else$><$lc("wwNoAccountsDefined")$><$endif$></td>
<td></td>

Insert the bold:

<td colspan=2 nowrap><$lc("wwAccounts")$></td>
<td colspan=2><$if UserAccounts$>
 <$rsMakeFromString("UserAccountsRS", UserAccounts)$>
 <$rsSort("UserAccountsRS", "row")$>
 <$accountOutput = ''$>
 <$loop UserAccountsRS$>
 <$if userHasAccessToAccount(row, 15)$>
 <$accountOutput = accountOutput & row & ' (RWDA) '$>
 <$elseif userHasAccessToAccount(row, 7)$>
 <$accountOutput = accountOutput & row & ' (RWD) '$>
 <$elseif userHasAccessToAccount(row, 3)$>
 <$accountOutput = accountOutput & row & ' (RW) '$>
 <$elseif userHasAccessToAccount(row, 1)$>
 <$accountOutput = accountOutput & row & ' (R) '$>
 <$endif$>
 <$endloop$>
 <$accountOutput$>
 <$else$><$lc("wwNoAccountsDefined")$><$endif$></td>
<td></td>

Good luck.

ADSG		Role/Account
admin	»	admin
contributor	»	contributor
intern	»	intern
Corporate_R	»	Corporate(R)
ImageLibrary_RW	»	ImageLibrary(RW)

ADSG		Role/Account
dev-admin	»	admin
dev-contributor	»	contributor
dev-intern	»	intern
dev-Corporate_R	»	Corporate(R)
dev-ImageLibrary_RW	»	ImageLibrary(RW)
dev-all	»	#all
dev-none	»	#none