Organizational Units (ou=org units,dc=berkeley,dc=edu)
The CalNet Directory includes a complete hierarchical representation of the entire UC Berkeley campus organizational unit structure. This information is publicly available and can be accessed by all anonymous and privileged application binds (accounts) for use in their applications. The Organizational Unit, or "Org Unit" data structure is refreshed nightly from data provided by the Enterprise Data Warehouse (EDW). This data allows applications to grant permissions to or collect information for units on Campus at various levels such as College, Department, or Payroll unit. It will be used when implementing roles information.
The entire Org Unit structure resides in the node ou=org units,dc=berkeley,dc=edu of the CalNet Directory. (see figure 1).
This node is not recognized as part of the campus structure, but merely a container to encapsulate the entire structure within a logically named node/OU.
Applications should use this node as the search-base for all queries. If the entire Org Unit structure needs to be examined from the beginning, recursive searches with scopes of "one" will need to be used in order to not exceed the Directory Search Results Limit.
Please refer to the Programmatically Exploring the Organizational Unit Tree Structure section for more information.
Description |
Figure 1: Organizational Unit Hierarchy |
---|---|
Within this top-level 'org units' branch of the Directory resides the ou=UCBKL Campus Root node. This node is the base, or root, of the entire UC Berkeley Organizational Tree. All Berkeley-related organization units are located within the ou=UCBKL Campus Root node. |
|
The ou=UCBKL Campus root node
The ou=UCBKL Campus root node is the top node of the organizational unit of the Berkeley Campus and it is the parent of all other campus organizational units. This entry can be located by searching the Directory using either of the following sets of criteria:
searchbase: "ou=org units,dc=berkeley,dc=edu" scope: "one" filter: '(objectclass=*)' |
or
searchbase: "ou=org units,dc=berkeley,dc=edu" scope: "subtree" filter = '(ou=UCBKL)' |
Below is an example of the Campus Root Node entry as returned by the Directory:
dn: ou=UCBKL,ou=org units,dc=berkeley,dc=edu
description: UC Berkeley Campus
ou : UCBKL
objectclass = top
objectclass = organizationalunit
objectclass = berkeleyEduOrgUnit
berkeleyEduOrgUnitHierarchyString = UCBKL
The Campus Root node entry does not contain the berkeleyEduOrgUnitParent attribute.
The berkeleyEduOrgUnit objectclass
Each organizational unit entry in the org-unit structure is based upon the berkeleyEduOrgUnit objectclass and has been designed to make it as easy as possible for applications to target the data they need.
Below is the LDAP schema definition of the berkeleyEduOrgUnit objectclass:
objectClasses: ( 1.3.6.1.4.1.4995.2.600.20.1
NAME 'berkeleyEduOrgUnit'
DESC 'Organizational Units'
SUP organizationalUnit
STRUCTURAL
MAY ( berkeleyEduOrgUnitParent
$ berkeleyEduOrgUnitProcessUnitFlag
$ berkeleyEduOrgUnitHierarchyString
)
X-ORIGIN ('user defined' 'Berkeley.edu University defined') )
The berkeleyEduOrgUnit objectclass is based upon Netscape's standard organizationalUnit LDAP objectclass and extends its functionality with the addition of three new attributes:
- The berkeleyEduOrgUnitParent attribute.
- The berkeleyEduOrgUnitProcessUnitFlag attribute.
- The berkeleyEduOrgUnitHierarchyString attribute.
Each of these attributes will be explained in detail in subsequent sections.
The berkeleyEduOrgUnitParent attribute
This multi-valued attribute contains the org-unit code for each parent Org Unit associated with in the hierarchy of the a given entry.
For example, let's examine the values of the berkeleyEduOrgUnitParent attribute found in the organizational unit ou=VRIST:
berkeleyEduOrgUnitParent: UCBKL
berkeleyEduOrgUnitParent: AVCIS
The ou=VRIST Org Unit only has two parent entries: ou=UCBKL, which is the Campus Root Node, and ou=AVCIS (Information Sys & Technology) (see figure 1).
Applications should not rely on the order that values from a multi-valued attribute are returned. There is no guarantee that the middleware used to enable LDAP support in any application will preserve the order of multi-values returned by an LDAP server.
The berkeleyEduOrgUnitProcessUnitFlag attribute
Every node under the root node is either a "Control Unit" or a "Process Unit." This can be determined by examining the 'berkeleyEduOrgUnitProcessUnitFlag' attribute:
berkeleyEduOrgUnitProcessUnitFlag: true
If 'berkeleyEduOrgUnitProcessUnitFlag' attribute is defined and set with a value of 'true,' the entry/node is a "Process Unit."
The berkeleyEduOrgUnitHierarchyString attribute
This single-valued attribute contains the entire ou hierarchy of an Org Unit, expressed in terms of a single string.
For example, let's examine the value of the berkeleyEduOrgUnitHierarchyString attribute found in the organizational unit ou=JICCS:
berkeleyEduOrgUnitHierarchyString: UCBKL-AVCIS-VRIST-JICCS
The Org Unit ou=JICCS is located three levels beneath the Campus Root Node (UCBKL). Notice that the hierarchy string preserves the exact order of the hierarchy (unlike the berkeleyEduOrgUnitParent attribute).
This allows applications to easily determine the immediate parent of any Org Unit. In the above example, we see that ou=VRIST is the parent of ou=JICCS
Example of a Process Unit entry
Using Ldap Filter:
'(ou=JICCS)' |
dn: ou=JICCS,ou=VRIST,ou=AVCIS,ou=UCBKL,ou=ou=org units,dc=berkeley,dc=edu
description: Central Computing Services
ou: JICCS
berkeleyEduOrgUnitProcessUnitFlag: 1
berkeleyEduOrgUnitParent: UCBKL
berkeleyEduOrgUnitParent: AVCIS
berkeleyEduOrgUnitParent: VRIST
berkeleyEduOrgUnitHierarchyString: UCBKL-AVCIS-VRIST-JICCS
objectclass: top
objectclass: organizationalunit
objectclass: berkeleyEduOrgUnit
Example of a Control Unit entry
Using Ldap Filter:
'(ou= VRIST)' |
dn: ou=VRIST,ou=AVCIS,ou=UCBKL,ou=ou=org units,dc=berkeley,dc=edu
description: Info Systems & Technology
ou: VRIST
objectclass: top
objectclass: organizationalunit
objectclass: berkeleyEduOrgUnit
berkeleyEduOrgUnitParent: UCBKL
berkeleyEduOrgUnitParent: AVCIS
berkeleyEduOrgUnitHierarchyString: UCBKL-AVCIS-VRIST
Directory Search Results Limit
In an effort to limit "email harvesting," the CalNet Directory will not return search results to any query that results in more than 500 entries. Thus, a query for all control units under the root node using the filter '(berkeleyEduOrgUnitParent=UCBKL)' with a scope of 'subtree' and a search-base of 'ou=org units,dc=berkeley,dc=edu', though valid, would fail since there are more than 500 control-units under the Campus Root Node. Applications that need to explore the entire tree will need to perform a series of smaller recursive-like queries, rather than a single large query.
Please refer to the Programmatic Exploration the Organizational Unit Tree Structure section for more information.
Programmatic Exploration of the Organizational Unit Tree Structure
As previously noted, the CalNet Directory will not return search results to any query that results in more than 500 entries. Under this restriction, applications will need to be careful in the manner in which they search the org-unit hierarchy.
Included below is a sample PERL script that demonstrates how to recursively browse the entire Org Unit structure without exceeding the directory search-result limit.
#!/bin/perl use Mozilla::LDAP::Conn; $LDAPSRVR = 'caldir.berkeley.edu' ; $LDAPPORT = '389' ; $LDAP_SEARCH_BASE = 'ou=UCBKL,ou=Org Units,dc=berkeley,dc=edu' ; $conn = new Mozilla::LDAP::Conn($LDAPSRVR,$LDAPPORT, '' , '' ); die "Couldn't connect to LDAP server $LDAPSRVR" unless ($conn); # initial call to recursive search function. # searching will begin at the Campus Root Node, which # is passed into the function as a required parameter. &traverse_org_unit($LDAP_SEARCH_BASE); exit( 0 ); ############################################################################## sub traverse_org_unit() ############################################################################## { my ($start_dn) = @_ ; my ($entry, $dn, $ldap_scope, $filter, $dn) = "" ; my ( @dns , @attributes ) = (); @attributes = ( "ou" ); $ldap_scope = "one" ; $filter = "(ou=*)" ; # search the directory for all entries 1 -level # beneath the $start_dn $entry = $conn->search($start_dn, $ldap_scope, $filter, 0 , @attributes ); if (! $entry) { # No child org-units found } else { while ($entry) { # fetch the DN for each entry found, # and push it onto the dns array. $dn = $entry->getDN(); push ( @dns ,$dn); print "Org-Unit: $dn\n" ; $entry = $conn->nextEntry(); } } # recursively call self using each dn in dns array # as the parameter foreach $dn ( @dns ) { &traverse_org_unit($dn) } } |
Example Search Filters and Settings
To search for... |
search-base |
scope |
filter |
---|---|---|---|
all Process Units: |
ou=org units,dc=berkeley,dc=edu |
subtree |
(berkeleyEduOrgUnitProcessUnitFlag=*) |
all Units under Control Unit 'VPUEI': |
ou=org units,dc=berkeley,dc=edu |
subtree |
(berkeleyEduOrgUnitParent=VPUEI) |
all Process Units under Control Unit 'VRIST': |
ou=org units,dc=berkeley,dc=edu |
subtree |
(&(berkeleyEduOrgUnitParent=VRIST)(berkeleyEduOrgUnitProcessUnitFlag=*)) |
all Control Units under Control Unit 'VRIST': |
ou=org units,dc=berkeley,dc=edu |
subtree |
(&(berkeleyEduOrgUnitParent=VRIST)(!(berkeleyEduOrgUnitProcessUnitFlag=*))) |
all Units directly beneath Control Unit 'VRIST': |
ou=VRIST,ou=AVCIS,ou=UCBKL,ou=org units,dc=berkeley,dc=edu |
one |
(objectclass=*) |