Abstract

The Repository Interrogation Utility allows a user to navigate repositories, perform a properties dump, view the type tree of a repository, execute API commands and run DQL or xDQL queries. The utility now includes some additional features such as integration with the 'Object Reference Manual', a listing of SBOs and detection of registered TBOs. The utlity is available as both a standalone application and an Eclipse plugin. The standalone application can be used without the need to know or install the whole Eclipse IDE.

Note:In the following article the word 'type' refers to a repository type such as 'dm_sysobject', 'dm_user,' and so on. The word 'object' refers to an instance of a 'type'.

Announcements

Poll
We are trying to determine whether we can move Repoint to Eclipse 3.3 to make use of some SWT 3.3 features. To participate in the poll to determine the most popular version of Eclipse click here.

Next Version
A development build of the next version of Repoint has been published. The new version includes major changes to the Repository Browser and the Query View in terms of performance and UI. The latest build of Jan 29th includes bug fixes and new Beanshell scripting view. Read more...

Shortcuts

• List of Updates
• Download and Install
• Project Services
• Properties View
• Repository Navigation View
• Type View
• Query View
• API View
• SBO View
• DFC Trace View

• Integration with Server Object Reference Manual
• XSL Transformation
• Deep Export
• Create Select Query
• Asynchronous Query Execution
• Asynchronous XDQL Query Execution
• Save Properties Dump to an MS Excel Compatible File
• Save DQL Query Results to an MS Excel Compatible File

Updates

Dec 17, 2007
The latest development build of the next version of Repoint has been posted with bug fixes. Read more...

Sept 5, 2007
The latest development build of the next version of Repoint is now working on Documentum 6. Read more...

July 29, 2007
A development build of the next version of Repoint has been published. The new version includes major changes to the Repository Browser and the Query View in terms of performance and UI. Read more...

January 10, 2007
Harjit Singh from Flatirons Solutions Corporation has contributed an extension to Repoint that creates a DQL statement from a type. To use this feature Right-click on a type in the Type View and select 'Create DQL..'

Nov 30, 2006
Koders.com have indexed the Repoint projects' source code on Sourceforge.net. This allows developers to search for code samples within the Repoint source code. Search

Oct 2, 2006
The build released on Sept 27, 2006 was not working with JRE 1.4.2. We have updated the build to now work with JRE 1.4.2. The issue occurred because the Eclipse Plugin builder does not use the project settings which had been set for compiling to JDK 1.4. We had to explicitly configure the Plugin builder to create target class files for JRE 1.4.

Sept 27, 2006

• A Trace View has been added to Repoint that allows monitoring of DFC traces. This view allows configuration of DFC tracing
• The Repoint standalone launcher has been changed to an executable (repoint.exe). It auto-detects the DFC configuration needed by Repoint. Thus, it is not necessary to manually set environment variables and use a shell script - startRepoint.cmd.

June 22, 2006
The source code for the tool has been released on Sourceforge.net under the BSD license

May 10,2006

• Properties View - Fixed a bug that did not save the properties dump correctly to an excel file. The bug was introduced when the categorized properties view was introduced.
• Deep Export - Fixed a bug related to DFC 5.2.x

May 8, 2006

• Properties View - Fixed a bug that did not show the Single/Repeating category of an attribute during a type dump.
• Query View - Added an option to execute XDQL queries asynchronously. This option is useful for long running queries.
• Absence of the dfc.properties file will now display an explicit error prompt instead of silently logging the error.

April 21, 2006

• Properties View -
  • Modified to categorize the properties. Each category can be collapsed/expanded to hide or show it.
  • Added 'Back' and 'Forward' buttons to navigate previous/next dumped objects.
  • Fixed a bug that prevented 'ENTER' keyboard button from dumping object properties. Now typing or pasting an id in the box and hitting 'ENTER' will dump type/object properties.
• Repository Navigation -Added categories to the listing of folder contents. All folders show up first, then documents and finally other sysobjects.
• API View - Fixed bugs related to execution of script files that prevented files with comments and multiline commands from executing.

March 29,2006

• Added an API view to execute DMCL API commands (similar to IAPI). The view includes code assist and api syntax reference.
• Properties View - Added ability to view repeating attribute indices.
• Modified the asynchronous DQL query execution feature to write results to file to avoid out of memory errors for queries with very large result sets. This will now use a separate Repository session to avoid hanging the UI.

Feb 10, 2006

• The Repository Type View that used to show the object types in the repository has been modified to show additional data. The view now has special nodes for the following types of objects - dm_policy, dm_process, dm_method, dm_job, dm_format, dmc_module(TBOs, SBOs and other custom modules), XML applications and DocApps. Please see the section on Type View for more details.
• Properties View -
  Added ability to filter custom properties.
  It is now possible to select multiple attributes and create a DQL SELECT query, which can be executed from the Query View. Please see the para on Create Select Query for more details.

Nov 16, 2005

• Added the XSL Transform capability to the plugin.
• Descriptions for custom object types can now be added to the context-sensitive object reference.
• Changed the behavior for displaying virtual document children. The children are displayed in the same order as specified by DFC. Previously, they would be sorted alphabetically based on the object_name.

Oct 12, 2005
Corrected a bug that prevented detection and display of Business Objects on DFC 5.2.x

Project Services

The source code for the Repository Interrogation Utility is now available on Sourceforge.net. It has been released under the BSD license. Please feel free to file bugs or feature requests on the project page

Note:The binaries are still hosted on the developer website. If you want just the binaries and not the source, scroll down and look for the download link

• Project Page
• Building the Source Code
• File Bugs
• Feature Requests

Properties View

The properties view has two purposes -

• It is used to show the properties of an object and their values. Example, object_name - 'My New Document', i_folder_id - '0b12d69680000521'.
  
  
  
  Fig Properties dump of an object selected from the Repository Tree
  
  
• It is used to show the various attributes of a repository type i.e. provide information regarding the type. Example, i_chronicle_id is a Single valued attribute of type 'ID'.
  
  
  
  Fig Attribute information of a type selected from the Type Tree
  
  

Features

• The attribute list is alphabetically sorted in an ascending manner.
• Double-clicking an object in the 'Repository Tree View' or a type in the 'Repository Type View' displays the properties of an object or a type respectively.
• Double-clicking a property from the properties view, whose value is an ID will dump the properties of the object represented by that ID.
  
  
  
  Select and double-click an id to dump its properties
  
  
• You can also explicitly paste an object id(e.g 0b12d69680000521) or a type name(e.g. dm_user) into the box at the top of view and request a properties dump.
• All non-inherited(custom) attributes of a type are now shown with red color. This is particularly useful when navigating the type tree to find out what attributes a child type has added to the parent's attributes. In the second image, the attributes shown in red are those that dm_category adds to the ones inherited from dm_folder.
• Some common attributes are shown in blue color so that they can be easily read in the dump.
• It is possible to filter custom properties by right-clicking anywhere in the properties view and select 'Show Only Custom Properties'
  
  
  
  Show Only Custom Properties
  
  The following image shows the properties view displaying only custom properties -
  
  
  
  Properties View Showing Only Custom Properties
  
  
• Double-clicking a repeating attribute whose values are of type ID will show a list of the ids and allow a user to select one of them to be dumped.
• Selecting a repeating attribute by clicking on it will show its values alongwith their indices in a popup list. If the repeating attribute values are object ids, you can click on one from the popup list to dump its properties.
  
  
  
  Repeating Attribute Indices
  
  
• When the view is showing properties of an object, double-clicking the 'r_object_type' property will dump the corresponding type description.

Repository Navigation (Repository Tree View)

This view allows a user to navigate the repository as a tree structure of folders and objects. The tree shows folders and all dm_sysobjects contained within a folder and not just dm_documents. Thus, it would also show objects such as dm_process or dm_method in the tree. In addition to this, if a document is a virtual document, it can be expanded inline within the tree.



Fig Repository Navigation

Features

• First and foremost, a user must add a repository to the view in order to see its contents. There are buttons to add and remove repositories from the repository list.
  
  
  
  Add a Repository to the Tree View
  
  
• Double-clicking an object in the tree dumps the object's properties in the Properties View discussed earlier.
• An object (e.g. folder) can be refreshed by right-clicking and selecting 'Refresh'. For example, if some documents have been added to a folder using another application such as Webtop, the folder's contents can be refreshed.
• Right-clicking a repository node gives menu items to view the connention config object, server config,....
  
  
  
  Session Information
  
  

Repository Type Tree View

The following categories are displayed for each repository - Lifecyles, Processes (Workflows), Jobs, Methods, Formats, Modules, Relation Types, Applications (Doc Apps). Expanding each of these categories shows the corresponding objects in the repository.

Object Types
The 'Object Types' node is the erstwhile type tree. It is the same functionality except it is now a peer to other categories. The type tree shows the type hierarchy in a repository as a tree. Example, dm_document is a child of dm_sysobject or dm_cabinet is a child of dm_folder which is a child of dm_sysobject. Double clicking on a type shows information about its attributes in the Properties view discussed earlier. The type view is shown in Fig 2.

Note:From the figure you can see that a '+' sign is shown next to all types. This does not mean that all the types may have subtypes. For performance reasons, a types subtypes are not found till a user explicitly requests its subtypes to be shown.

Features

• First and foremost, a user must add a repository to the view in order to see its types. There are buttons to add and remove repositories from the repository list.
• Double-clicking an object in the tree dumps the object's attributes.
• The object type tree will show the text '[TBO]' next to types that have a Type-based Business Object (TBO) associated with them. Right-clicking and selecting 'Show TBO Description' will show more information about the TBO like its implementation class. The amount of information displayed could vary depending on whether DFC version is 5.3 or 5.2.x
  
  
  
  Show TBO Information
  
  
• Right-clicking a dm_policy (lifecycle) node and clicking on 'Show Objects With this Policy' will create a query for finding all objects that have the corresponding policy attached and open the Query View. Note that the query is not executed. You will need to execute it from the Query View. This is done so that you can add any qualifications to the query for filtering the results.
  
  
  
  Query for Objects with Lifecycle
  
  
• You can query for all workflows created from a dm_process by right-clicking on a dm_process node and selecting 'Query for Workflows Instantiated Using this Process'.
  
  
  
  Query for Workflows
  
  
• You can find the dm_method that a dm_job executes by right-clicking on the dm_job node and selecting 'Show Method for Job'. This dumps the methods attributes in the Properties view.
  
  
  
  Show Method for the Job
  
  

Query View

This view provides UI to execute a DQL or XDQL query and view the results. The portion of the query view that shows the table/browser is vertically expandable, i.e. it can be pulled upwards/downwards to increase/decrease the result area.

Features

• DQL results can be column sorted (ascending only) by clicking on the column name
• If a cell of the results table contains an object id, double clicking it dumps its properties in the Properties view. A dump can be also requested by right clicking and selecting 'Dump Properties' from the context menu.
  
  
  
  Dump Properties from Query Results
  
  
• The repository to be queried against can be selected by clicking on the Repository button, which is there in toolbar of the Query View. The current repository being queried will be mentioned just above the query text box.
  
  
  
  Query View Options
  
  
• The query text box colors reserved DQL keywords and object types. The types are dynamically obtained from the current repository being queried.
• In the query text box, a user can cycle through previous queries of the session using the UP and DOWN arrow keys. This is similar to the way one might cycle through commands in a DOS/Unix command shell. Pressing RETURN(ENTER) executes a DQL query. You can also view the old queries by clicking on the yellow up-arrow button in the Query View.
• You can store a query as a favorite query (i.e. bookmark it) by clicking on the blue 'bookmark' button. A favorite query is persisted across sessions. To view your favorite queries click on the menu(down arrow key). The favorite queries are stored using the Eclipse preference service, which typically stores it in a user's workspace folder.
  
  
  
  Favorite Queries
  
  

Fig 6 - xDQL Results

Note:A bug prevents the right click menu from showing up in the query box. However, CUT/COPY/PASTE can still be done using the keyboard using Ctrl-X(Cut),Ctrl-C (copy), Ctrl-V (paste) and Ctrl-A(Select All).

SBO View

This view shows all the registered Service-based Business Objects(SBOs). If the DFC version is 5.3, the SBO list is obtained from the global registry. If DFC is 5.2.x, the list is obtained from Documentum Business Objects Registry (DBOR). Double-clicking on a SBO shows more information about the SBO such as its implementation class.

Note:A possible bug prevents obtaining the list of interfaces and the dependency list of non-dynamically provisioned SBOs.

API View

Note:The following section, when it talks about the 'first token' refers to the command name. For example, in get,c, 0b017a12800003a7,object_name, the 'first token' is the command name 'get'

API View

The API view allows a user to execute DMCL API commands. The command can be entered on the single line box on the API view. To run the command, you can hit RETURN (ENTER) or click on the 'Execute' button. The API commands are executed using DFC methods IDfSession#apiExec(...), IDfSession#apiSet(...), IDfSession#apiGet(...). You must select a Repository before executing the api commands. Repoint expects the second token in the command to be 'c', which means the current session and it will autopopulate this token when you type in the ',' after the api command. Internally repoint maps the command to its category such as dmAPIExec, dmAPISet, dmAPIGet based on three files that contain the listing of the api commands obtained from API Reference Manual. These files are present in the folder $HOME/plugins/com.documentum.devprog_xxx/data, where $HOME can be ECLIPSE_HOME or REPOINT_HOME depending on whether you are using the eclipse plugin or the standalone version of Repoint.

API Reference
When a user starts typing in a command name, the possible matches are displayed in the reference list box below the command text box. One of the matches can be selected by using the mouse or by hitting the DOWN_ARROW key, selecting a command and hitting ENTER. Selecting a method from the list or entering the ',' after the api command name (first token), will show the command syntax in the box next to the list.

History
A user can cycle through old api commands(history) by pressing the UP or DOWN Arrow keys on the keyboard. Note that this functionality is not active if a user is typing the command name (first token) because at that time the UP and DOWN arrow keys are used to navigate the possible api command matches in the reference list box (see previous para).

Script File
A script file can be executed by typing its full path prefixed with an '@' sign. Instead of typing the path, it is possible to browse and select the file by clicking on the 'Choose Script File' button.



Choose Script File

Note:A bug prevents the right click menu from showing up in the command and the results. However, CUT/COPY/PASTE can still be done using the keyboard using Ctrl-X(Cut),Ctrl-C (copy), Ctrl-V (paste) and Ctrl-A(Select All).

DFC Trace View

The trace view enables monitoring of DFC traces. For this view to function, tracing needs to be enabled in the dfc.properties file. Repoint opens up a TCP socket and listens for trace messages on it. Thus, log4j.properties needs to be changed to send trace messages using a TCP socket instead of writing it to a file. These configurations can be made using the configuration dialog in the Trace View. To open the configuration dialog click on the 'pencil/pen' icon. If you want to do these changes manually, the steps are outlined in the next few paragraphs.

Note:Unfortunately, tracing does not work for Repoint itself. This is because we have not been able to get the Eclipse framework to successfully find the log4j.properties file. Once this is fixed tracing will work for Repoint too.

Changes to dfc.properties
If the following properties do not exist, add them to your dfc.properties -

dfc.tracing.enabled=true

dfc.tracing.compactMode=on
dfc.tracing.combineDMCL=true
dfc.tracing.recordParameters=on
dfc.tracing.recordReturnValue=on
dfc.tracing.stackDepth=100
		

Changes to log4j.properties
Look for the property log4j.appender.FILE_TRACE and change its value to org.apache.log4j.net.SocketAppender. Also, add the following property-value pairs to the file -

log4j.appender.FILE_TRACE.Port=4445
log4j.appender.FILE_TRACE.RemoteHost=localhost
		

Using the Trace View
Once configuration is complete, you can start tracing by clicking the 'Start' button (the triangle icon). To stop tracing press the 'Stop' button (the red square icon). Note that stop does not really disable tracing or modify the log4j properties file. It simply does not show trace entries in the view area. Pressing 'Start' again will start showing trace entries in the trace view area.

Error Traces
Any trace entries containing 'Exceptions' or 'Errors' are highlighted with a red background.

Trigger Words
It is possible to set trigger words, which tells Repoint to highlight any incoming (new) trace entry containing any of those trigger words. To set these, click on the 'abc' icon.

Integration with Object Reference Manual

Object Reference
Right-clicking a type name from the Type View and clicking on 'Description' will show you description of the type extracted from the Content Server Object Reference Manual. In addition, you can request description of any type by clicking on 'Description of' instead.



Requesting Type Description





Type Description Dialog

To add descriptions for custom types, edit the file HOME/plugins/com.documentum.devprog.eclipse.objReference_n.n.n/data/customTypes.xml . If such a file does not exist please create it. Sample contents of this file are as follows -

<?xml version="1.0" ?>
<objref>
<!-- Add a type element for each type -->
<type name="my_type">
<desc>
<p>
<!-- Put description within the p elements. It can be any valid HTML -->
Hello, my type does such and such a thing.
</p>
</desc>

<!-- Add an attr element for each attribute -->
<attr name="my_attr">
<desc>
<p>
<!-- place attr description here. It can be any valid HTML -->
my_attr is a string attribute that does something.
</p>
</desc>
</attr>
</type>
</objref>

Attribute Reference
Right-clicking an attribute from the Properties View and selecting 'Description' will display the attribute's description extracted from the Content Server Object Reference Manual. This is useful if you want to obtain additional information about an attribute than just its data type and whether its single/repeating. This feature works both when the view is showing the attributes of a type or of an object.



Requesting Attribute Description





Attribute Description

Deep Export

The tree view bundles the 'Deep Export' functionality available on the component exchange. This allows the export of a complete folder hierarchy from the repository. You can invoke the deep export functionality by right-clicking on a folder and selecting 'Deep Export Folder'. The deep export runs in the background and its completion status can be seen in the progress view. Once complete, the progress view provides a link to open the exported folder. Progress of the asynchronous job can also be seen in the bottom right corner of the window.



Deep Export

Create SELECT Query

It is possible to select multiple attributes and click on the 'Create SELECT Query' option from the context menu to generate a DQL SELECT query for the current type and selected attributes. The query is not executed. Instead it is generated and populated in the Query View. You can edit the query and add any additional qualifications before executing it from the Query View.



Create SELECT Query





Created SELECT Query

XSL Transformation

XSL Transform Dialog

XSL Transformations can be perfomed by invoking the feature from the popup menu. To transform an XML file in the repository select the file, right-click and choose 'XSL Transform Repository File'. This will open the transform dialog. The XML and the XSL files can be local or in the repository. If a repository has been selected, the transform is carried out using the DFC Transform operation and the repository session. This can be used to test XSL files containing xdql locally before putting them into the repository. For example, we used the tool to develop and test our Webpublisher XSL presentation files before updating them in the repository.



Invoking XSL Transform

If both files are local and no repository has been selected (i.e. no repository session available), the transformer obtained from javax.xml.transform.TransformerFactory is used. If the files needed for the transform are both local and do not need a repository session, it might be better to choose the 'XSL Transform Local File' option from the popup-menu.

Asynchronous DQL Query Execution

DQL queries can also be executed in the background (i.e. asynchronously). This feature can be used for long running queries so that they don't block the user interface. The query progress and its status will be shown in the progress view. The results can be viewed by clicking on the blue link under the query job in the progress view. It is possible to start more than one background query. Unlike a regular query, an asynchronous query does not display its results in the results table viewer. Instead it will save the results to a TAB separated file. This is done so as avoid having to maintain a large number results in memory.

This feature uses Eclipse Jobs framework, where each asynchronous query is executed in a different job. Each query runs in a different Documentum session created using IDfSessionManager#newSession() so as to not block the UI which uses a different session. To execute a query asynchronously, click on the blue circular icon on the Query View's toolbar instead of the regular 'DQL' button. This will prompt you for a file to save the results to and then start the query execution job.



Execute DQL Asynchronously

Asynchronous XDQL Query Execution

XDQL queries can be executed in the background. This is particularly useful when the 'Include Content' option is enabled for XDQL queries. With this option the query execution can be resource intensive and can take a long time. Such queries can be executed asynchronously, which executes the query in a separate session so as to not lock up the UI and stores the results in a file to conserve UI resources.

Save Properties Dump to a MS Excel Compatible File

The attribute dump in the properties view can be saved to a file using the 'Save' button on the toolbar of the Properties view. The dump is saved as a TAB separated file that can be opened using MS Excel. It is possible to save both the object properties dump and a object type description dump. If the custom property filter is enabled, it also possible to save just the custom properties from the view.



Save Properties to a Excel Readable Format

Save DQL Query Results to a MS Excel Compatible File

The DQL results can be saved to a Comma-Separated Value (CSV) file that can then be opened using MS Excel. To do this, click on the 'Save' icon in the toolbar of the Query View.

Acknowledgements

Many thanks to

• Tiana Scott from EMC Documentum Tech Pubs who helped us with the integration of tool with the Object Reference Manual. She painstakingly formatted the manual so that the tool could extract information correctly from it.
• Curt Shehow for suggesting features such as repeating attribute indices, API View and for pointing out bugs in large query execution and deep export. He has also suggested some other features on which we are still working.
• Harsh Hatekar from EMC Consulting for suggesting features such as seperating custom properties from which Properties categorization was born, Back/Forward navigation for Properties view, API View and for pointing out bugs in the API View.
• Johnny Gee and Steve Bickle for suggesting the API View on the support forums.
• Victor Spivak from EMC Documentum Engineering for suggesting TBO detection in the type view.
• Ingo Zittman for his suggestion of adding the 'start' command to the startRepoint.cmd file that causes the command prompt window to automatically close after startup.
• Mahesh Ganapathy for pointing out the bug with the Properties view not displaying S/R during a type dump.
• Chris Rink from EMC Customer Support for suggesting a utility for viewing DFC traces. This resulted in the addition of the Trace View in Repoint. Suggestions from Chris also resulted in making the standalone Repoint launcher an executable that auto detects the Java home and DFC Configuration.
• Alex Oscherov from DFC/Server Engineering for his inputs and comments on the DFC Trace View

About Contributors

Harjit has contributed an extension to repoint that creates a DQL statement for a type. Harjit works for FlatIrons Solutions as a Consultant. His areas of expertise are Java, C++, J2EE,WDK,MTS,DFC,JSP,Server Methods. You can contact him at(Harjit.Singh@flatironssolutions.com)

Download and Install

The Repository Interrogation Utility can be installed either as a standalone application or as an Eclipse plugin.

• Installation instructions for the standalone version , which does not need the install or knowledge of the Eclipse IDE.
• Installation instructions for the Eclipse plugin that fits into the Eclipse IDE.

Discuss

Repoint Discussion Forum