Monday, April 27, 2009

Expanding Your Search Results

When you run a search in Oracle UCM, the system will max out the number of documents it returns according to the MaxResults variable.  The default value for this is 200, and you can change this number in your config.cfg file.  Be warned that increasing this number beyond 200 can have adverse effects on your search performance, so use this with caution.

Another Method of Expansion

But what if, on a rare occasion, you do need to get extra search results, but don’t want to modify the configuration file so as to affect all searches?  This post demonstrates some simple IDOC code that will expand your search results.

Sample HCSP

For this example, we’ll put the code in a simple HCSP page.  The same strategies would work just as well inside fragments, components, or other code sources.
Create a basic SearchResults.hcsp page.  I always like to put in some basic HTML code first to aid with display.   Once you have that set up, let’s start with the parameters for the search:

<!--$ QueryText = “” -->
<!--$ desiredResults = 500 -->
<!--$ maxResultsPerSearch = 200 -->


The QueryText variable is required to execute the search service.  By setting it to blank, we are getting all documents in the system.  You can put in your own properly formatted query here if you like.

The desiredResults variable is how many results we’d really like to see.  The maxResultsPerSearch variable is set to 200, the default maximum that we’ll get from a single search.  We can expand this code a little to accommodate a custom setting here:

<!--$ if MaxResults and MaxResults gt 0 -->
     <!--$ maxResultsPerSearch = MaxResults -->
<!--$ endif -->


This tests for the presence of the MaxResults configuration setting and, if it finds one, will swap that value in for maxResultsPerSearch.

We’re going to need one more variable to keep track of how many total search results we’ve found to date.

<!--$ runningTotal = 0 -->

Now that we’ve got these variables established, we can get our search results.  Remember, each time we run a search, we’ll be capped at 200 results, but we want to get 500.  This means we’ll need to run two 200-result searches and one 100-result search.  We’ll accomplish this by executing the search inside a loop.

<!--$ loopwhile runningTotal lt desiredResults -->

What we’re setting up here is a method to keep track of the total number of results we get.  As long as that number is fewer that the desiredResults, we have more searching to do.

We need to add some additional search parameters that are specific to each iteration of the search execution:

<!--$ ResultCount = desiredResults - runningTotal -->
<!--$ StartRow = runningTotal + 1 -->


I’m cheating a little bit on the ResultCount here.  Theoretically, this number could be well in excess of the search result cap.  I’m relying on Oracle’s internal processes to enforce the limit of 200 documents.  The StartRow will need to be different each time I run the search so that I don’t get duplicates.

Now that this is all set up, I can run the service and print the results:

<!--$ executeService("GET_SEARCH_RESULTS") -->
<!--$ loop SearchResults -->
     <li><!--$ dDocTitle --></li>
<!--$ endloop -->


I have a touch of housekeeping to do to make sure the loop continues (and more importantly, ends) properly:

<!--$ runningTotal = runningTotal + SearchResults.#numRows -->
<!--$ if SearchResults.#numRows eq 0 -->
     <!--$ break -->
<!--$ endif -->


I’m incrementing the runningTotal so I can keep track of my progress.  I’m also checking for a zero result set.  If that happens, then I’ve run out of results and need to break out of the loop.

All that’s left to do is end the loop!

<!--$ endloop -->

When you run this code, you should see 500 documents in your results.
Here is the code in its entirety (plus some minor formatting):

<html>
<head></head>
<body><!--$ QueryText="" -->
<!--$ desiredResults = 300 -->
<!--$ maxResultsPerSearch = 200 -->
<!--$ if MaxResults and MaxResults gt 0 -->
     <!--$ maxResultsPerSearch = MaxResults -->
<!--$ endif -->
<!--$ runningTotal = 0 -->
<ol>
<!--$ loopwhile runningTotal lt desiredResults -->
     <!--$ ResultCount = desiredResults - runningTotal -->
     <!--$ StartRow = runningTotal + 1 -->
     <!--$ executeService("GET_SEARCH_RESULTS") -->
     <!--$ loop SearchResults -->
          <li><!--$ dDocTitle --></li>
     <!--$ endloop -->
     <!--$ runningTotal = runningTotal + SearchResults.#numRows -->
<!--$ endloop -->
<ol>
<body>
<html>


One word of warning: this code will be executing a search service several times, so you may get some slower results. 

Friday, April 10, 2009

Security Groups and Accounts Overview (Part 3)

This is the third entry of a three-part series on Oracle UCM (Stellent) security.

How Access Works

Access to documents is defined by both the Security Group and the Account.  In order to perform an action (such as view the document or check in a revision), a user needs to have permissions to do so by BOTH the Role the user has (and, by extension, the Security Groups the user has) and the Accounts the user has.  Both the Role and the Account settings for that user must grant permission to perform an action.  If either the Role or the Account permission does not exist, the user will be unable to perform the action.

Note: if Accounts are not enabled, then the user needs access via the Role only; accounts are not considered.

Practical Usage

The following roles are defined in the system:

Role Security Groups
Employee Intranet (R)
IntranetManager Intranet (RW)
ExtranetManager

Extranet (RW)
Partner Extranet (R)

The following users exist in the system:

User Roles Accounts
John Employee dept (R)
Sally Employee
IntranetManager
dept (R)
dept/hr (RW)
Beth Employee
Intranet Manager
dept (R)
dept/legal (RW)
Mike Partner partner/all (R)
partner/acme (R)
Hugh Employee
IntranetManager
dept (RW)
Brian Employee
ExtranetManager
dept (R)
partner (RW)
Anne Employee
IntranetManager
ExtranetManager
#all (RWDA)


Let’s look at some sample documents in the system.

Document A

Security Group Intranet
Account dept/legal
Here’s the breakdown of how people can access this document:

User Highest Permission by Role Highest Permission by Account Final Permission
John

R

R

R

Sally

RW

R

R

Beth

RW

RW

RW

Mike

None

None

None

Hugh

RW

RW

RW

Brian

R

R

R

Anne

RWDA

RWDA

RWDA

Sally cannot check out this document, even though her Role allows it. Her account settings are too granular (dept/hr) to write to a document in the dept/legal account.  On the other hand, Hugh can check out this document, because his role allows it and his account setting of /dept (RW) will cascade down to accounts beneath it; so he has write permissions to all documents under the /dept account.

Document B

Security Group Extranet
Account partner/acme
Here’s the breakdown of how people can access this document:

User  Highest Permission by Role Highest Permission by Account Final Permission
John

R

None

None

Sally

R

None

None

Beth

R

None

None

Mike

R

R

R

Hugh

None

None

None

Brian

RW

RW

RW

Anne

RWDA

RWDA

RWDA

Most of these users cannot see this document at all because they do not have the account requirement.  Mike, the partner, can see this document just fine however.

Document C

Security Group Extranet
Account partner/abc
Here’s the breakdown of how people can access this document:

User Highest Permission by Role Highest Permission by Account Final Permission
John

R

None

None

Sally

R

None

None

Beth

R

None

None

Mike

R

None

None

Hugh

None

None

None

Brian

RW

RW

RW

Anne

RWDA

RWDA

RWDA

This document is similar to Document B, but the account is different.  Using the account, this system is able to put a document on the Partner Extranet that only some partners can see.  Notice how Mike is denied access to this document.

Monday, April 6, 2009

Security Groups and Accounts Overview (Part 2)

This is the second of a three-part series on Oracle UCM (Stellent) security.

Accounts

Accounts are an optional second layer of security that you can use inside the Oracle UCM.  To activate accounts, add the following configuration setting to you config.cfg file:

UseAccounts=1

Accounts differ from Security Groups and Roles in a couple of different ways:

  • Accounts are applied to documents and to users. 
  • Accounts have a hierarchy to them
A document can have only one account.  A user can have access to an unlimited number of accounts.
Accounts tend to be used for very granular levels of security, although the hierarchical nature of accounts allows for wide-spread access across several accounts.

A Sample Hierarchy

Accounts have a natural hierarchy to them.  This allows you to create extremely granular levels of security, but also gives you the ability to grant a wide range of access as needed.  This is fantastic for managers, executives, and administrators who need broad access to some of the content in the system.  It also allows you to fine-tune the distinction between read-access and write-access for several different types of users.

The account hierarchy is typically delineated with a slash (“/”).  The first level of the account tends to be very broad.  The account gets more and more specific as components are added to it.  For example:

Account Access
dept All departments
dept/mktg The marketing account
dept/legal The legal account
exec An account for executives
exec/ceo An account for the CEO
exec/cio An account for the CIO
exec/coo An account for the COO

A Common Account Mistake

Because Accounts get more specific and detailed the farther down the tree you go, many users of Oracle UCM create what they think is a highly secure group far down the hierarchy. 

Continuing the example from above, let’s say that you wanted to create a group of secure documents for managers within the marketing department.  Many people try this as an approach:

dept/mktg/managers

This is not a workable solution.  If you were to implement this account, all users who had access to dept/mktg would automatically get the same access to the “Managers Only” account.  This is exactly what you’re trying to avoid!  You can address this problem in a couple of ways:

  • Put the “Managers Only” account in another branch.  An account such as managers/mktg would keep these documents safe from people who have access to dept/mktg
  • Create a general account for marketing documents.  This will give you two new accounts: dept/mktg/managers and dept/mktg/general
  • Use the higher level account for more secure documents, and create a lower level account for documents with more generalized access.  This would entail putting the “Managers Only” content in dept/mktg and the regular marketing documents in a generic sub-account, such as dept/mktg/general.  Managers could have access to the dept/mktg account (and, by order of the hierarchy, dept/mktg/general as well), while regular users of the marketing department would have access into the dept/mktg/general account only.
Usually, the first option is most ideal solution.  (The other two are included just to help you get used to thinking about why account structures work in certain ways.)  The first option helps you set up your structure so that you can use high-level account assignments (such as just dept) to give broad ranges of access to users.

When dealing with accounts, it’s important to think not only about the documents, but also about how you will provide the access to users.  Some common questions to ask yourself as you’re preparing an account hierarchy:

  • How are these documents logically grouped together in terms of security?
  • Are there common groups of people who need to see the sub-groups inside this hierarchy?
  • Do we need to identify some documents for which there is either an expanded or contracted audience that has write access?
  • Do we need to identify some users who have expanded or contracted privileges for a subsection of these documents?

Predefined Accounts

System Administrators have the ability to establish Predefined Accounts in the User Admin.  By populating this list, System Administrators make the accounts available via drop-down lists.
Note: Accounts do not have to be defined in this list in order to be used, but doing so makes the management much easier.

Special Accounts

There are two special accounts defined within Oracle UCM:

  • #none
    • This is for documents with no account.  If a document has a blank or null account field, a user will need access to the #none account to perform actions on this document
  • #all
    • This is a catch-all account, and grants a user access to any and all accounts in the system.  Use this option with care.
Note: the #none and #all declarations are available only in the User Admin screen.  You assign these accounts to users, but do not assign them to documents.

Wednesday, April 1, 2009

Security Groups and Accounts Overview

Oracle (Formerly Stellent) provides several ways to restrict access to documents, and the terminology and structures can get somewhat confusing at times.  I’ve written this blog entry to help clarify some of these terms and help people get a better understanding of the concepts and terms involved with Oracle UCM security.

This blog entry is split into several sections  Today we’ll cover Security Groups and Roles, next up will be Accounts, and that will be followed by a couple of examples of how they all work together.

Security Groups

A Security Group is a categorization of security that is linked directly to a piece of content.  Documents have Security Groups; users do not.  I like to think of a Security Group as a broad section of security.  Every document must belong to one and only one Security Group.  By default, Oracle provides two Security Groups: Public and Secure.  Many people expand these to larger categories of broad security.  Some typical values are:

  • Use-based Security Groups:
    • Intranet/ Extranet/ Public
    • Internal/ External/ Officer
  • Department-based Security Groups
    • Legal/ HR/ Marketing
  • Location-based Security Groups
    • SanFrancisco/ Boston/ London
You can have as many Security Groups as you like in the system, but people tend to keep this number down to a minimum.  Remember, Security Groups tend to represent broad categorizations of security, so try to keep this number under control.  If you need more discrete control over document security, I recommend looking at Accounts.

Roles

A Role is a definition of access that a user has to specific Security Groups.  Each Role references one or many Security Groups.*  For example, the following roles may be defined in your system:

Role Access
Intranet Contributor Intranet (RW)
Reader Legal (R)
HR (R)
Marketing (R)
London Admin London (RWDA)
A Role is associated with one or many users, and a user can have many Roles. 

* Note: a Role can be used to define access to administrative applets as well; it is entirely possible to have a Role that does not address a Security Group.