Victor Vogelpoel

Excellence is in the details

Putting PowerShell to good use: discovering the OpenText eDOCS COM API

1 Comment


Intro to the series “Putting PowerShell to good use”

Five years ago, PowerShell fell into my lap and never left my lab again. PowerShell is not just for the system administrator, but a great tool for any developer as well. It lends itself well for all sort of tasks:

  • Discovering APIs;
  • Leveraging APIs;
  • Creating APIs;
  • Deployment;
  • Testing.

In these series “Putting PowerShell to good use”, I want to share here how I have been using PowerShell. In this first post: discovering APIs with PowerShell and in this post discovering the OpenText eDOCS COM API.

TL;DR

This new job at The ONE introduced me to Open Text eDOCS Document Management (previously Hummingbird) and Ultimus Business Process Management. Learning these products and leveraging their APIs for creating integration solutions is a bit of a challenge. PowerShell has been a great help in discovering the eDOCS API and its workings.

OpenText eDOCS

OpenText eDOCS DMOpenText eDOCS DM (formally Hummingbird eDOCS) holds its ground with a lot of clients who still support large archives of documents under compliance laws (mainly government, law firms and the larger institutes). The version my clients are working with is eDOCS 5.3.1, mostly with patch 4 or 5. The eDOCS DM server is a 32-bit program, although the eDOCS DM client extensions come in a 32-bit and 64-bit flavor.

In this post: Discovering the eDOCS DCOM API using PowerShell.

Discovering the eDOCS DCOM API

Try to find eDOCS API and integration information on the internet. Virtually non-existent! The complete opposite of finding information for SharePoint development for example, where a wealth of documentation, samples and solutions can be found. For a developer, eDOCS is a niche product in development land; nothing much is being published about its API or interfacing. OpenText does supply the eDOCS DM API documentation (revision May 2012) and this documentation describes the COM methods, along with a few sparse VBScript (!) samples and data dictionary for its database . It’s not much to go on if one has to create integration solutions.

I started discovering the eDOCS API and eDOCS workings by executing methods using the PowerShell command line and integrated script editor. Because of lack of content on the Internet, this makes it all the more fun for me to write something about the eDOCS DM API and solutions and combining this with my hammer of choice: PowerShell.

Discovering eDOCS, I am using a virtual machine with eDOCS server 5.3.1 patch 4 and the eDOCS DM Extensions installed. The eDOCS DM Extension is the client for the eDOCS server. It expands the Windows Explorer with a user interface for registering new documents, search and opening documents. It is implemented as COM objects that use the DCOM protocol to communicate to the eDOCS server. The eDOCS COM API comes in two flavors: the server DM COM API and the DM Extensions COM API. I used the latter in my quest to learning about eDOCS.

Enter PowerShell. I’d like to find out how eDOCS and its API works. With PowerShell, at least I can have a Read-Eval-Print loop (REPL) experience with the API and discover its operation and workings. PowerShell can work with COM objects, but fortunately an interop exists as well:

Hummingbird.DM.Server.Interop.PCDClient.dll

The eDOCS API interfacing model is:

Instantiate a class object
Assign parameters
Call execute()
Assert the call success
Do something with returned data

This was my first script for getting the available eDOCS login libraries via PowerShell:

add-type -path 'C:\Program Files\Open Text\DM Extensions\Hummingbird.DM.Server.Interop.PCDClient.dll'
$PDCLoginLibs = New-object Hummingbird.DM.Server.Interop.PCDClient.PCDGetLoginLibsClass
$rc = $PDCLoginLibs.Execute()
if ($rc -ne 0)
{
  throw $PDCLoginLibs.ErrDescription
}

$libraries = for ($i=0; $i -lt $PDCLoginLibs.GetSize(); $i++) { $PDCLoginLibs.GetAt($i) }
# $libraries now contains an array of eDOCS libraries
Write-Host "Libraries: $($libraries -join ', ')"

// Note that the $PDCLoginLibs object should be released using
//  [System.Runtime.InteropServices.Marshal]::FinalReleaseComObject

Running it resulted in a very big COM error:

New-object : Exception calling ".ctor" with "0" argument(s): 
"Retrieving the COM class factory for component with CLSID 
{BE9EA641-D07F-11D0-8383-00A0C92018F4} failed due to the 
following error: 80040154 Class not registered (Exception from 
HRESULT: 0x80040154 (REGDB_E_CLASSNOTREG))."
 At C:\SRC\test-eDOCSCOM.ps1:11 char:17
 + $PDCLoginLibs = New-object Hummingbird.DM.Server.Interop.PCDClient.PCDGetLoginLi ...
 +                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 + CategoryInfo         : InvalidOperation: (:) [New-Object], MethodInvocationException
 + FullyQualifiedErrorId : ConstructorInvokedThrowException,
Microsoft.PowerShell.Commands.NewObjectCommand

Why? The COM object cannot be instantiated? But eDOCS works just fine in the Windows Explorer via the DM Extensions!?

Looking up the COM class in the Window Registry, I dawned upon me: I was using a 64-bit PowerShell Integrated Script Editor (ISE) session to run a script that uses an interop to a 32-bit only COM API! Opening the 32-bit PowerShell editor and running the script now resulted in:

Libraries: SAMPLELIB

Success!

I later found out that there is a separate setup file for installing the 64-bit eDOCS COM API as well. With the 64-bit eDOCS DM COM objects installed, a 64-bit PowerShell session can use the eDOCS COM API as well.

And even logging on to a DM Library and searching for a document works:

$PDCLogin = New-object Hummingbird.DM.Server.Interop.PCDClient.PCDLoginClass
$rc = $PDCLogin.AddLogin(0, 'SAMPLELIB', 'ADMINISTRATOR', 'myvoiceismypassword')
if ($rc -ne 0)
{
   throw $PDCLogin.ErrDescription
}

$rc = $PDCLogin.Execute()
if ($rc -ne 0)
{
   throw $PDCLogin.ErrDescription
}

# Get the login token ("DST")
$dst = $PDCLogin.GetDST()
Write-Host "DST is `"$dst`""

# -------------------------------------------------------------------------------
# PCDClient.PCDSearch (Search document(s)):
# Search, retrieve result rows and release the results
$obj = New-object Hummingbird.DM.Server.Interop.PCDClient.PCDSearchClass
# Set the login token
$obj.SetDST($dst)
$obj.AddSearchLib('SAMPLELIB')
$obj.SetSearchObject('def_qbe')
$returnProperties = 'docname', 'docnum', 'AUTHOR_ID'
$returnProperties | foreach { $obj.AddReturnProperty($_) }

$rc=$obj.Execute()
if ($rc -ne 0)
{
  throw $obj.ErrDescription
}

# Gather the results
while ($obj.NextRow())
{
  $searchResults = @{}
  $returnProperties | foreach { $searchResults.Add($_, $obj.GetPropertyValue($_)) }

  # Output the search results
  $searchResults
}

$obj.ReleaseResults()

// Note that the $PDCLogin and $obj objects should be released using
//  [System.Runtime.InteropServices.Marshal]::FinalReleaseComObject
//

Other methods in the eDOCS API get, put, lock, unlock and update document registrations, or do enumerations on objects.

At first sight, the eDOCS API seem to be pretty low-level: you have to do multiple API calls in sequence to do something like registering a document in the document management system. It would be nice to have some high-level ‘business’ methods on top of this low-level API.

One thing I absolutely don’t like about the eDOCS COM API (or eDOCS) is the lack of discoverability. If you know Get-Help, Get-Command and Get-Member, you can find out anything about PowerShell commands or concepts. Even error messages help you discover. With eDOCS, you’re punished with ‘One or more properties are missing‘ with no clue what is missing or wrong in a call. Or it returns an HR error code, with ‘good luck finding out what mishappened’!

Concluding

Discovering the eDOCS COM API is one thing, using the APIs to discover the eDOCS DM workings is another. eDOCS is a complex product to master and it takes several API calls to accomplish something. Finding out why a call is returning an error or failing is a royal pain. The eDOCS API seems to be pretty low-level and lacks discoverability.

However, I am fortunate to have several eDOCS-knowledgeable colleagues, among one really good at harnessing the API into business functionality in C# code. This is also my guide in learning to use the eDOCS API properly.

PowerShell helps me to interactively discover the eDOCS COM APIs and work out proper method calling order to accomplish something. I think it is putting PowerShell to great use.

I’ve prepared the PowerShell code for eDOCS API samples at the GitHub site of The ONE: https://github.com/TheONESolutions/PuttingPowerShellToGoodUse.Samples

Next in the series: eDOCS DM has another API to discover: a WCF web service.

Disclaimer

This work is not affiliated with, maintained, authorized, endorsed or sponsored by the eDOCS DM vendor OpenText. eDOCS DM is a trademark of OpenText. All other names and/or marks listed in this article are the property of their respective owner. Victor Vogelpoel works for The ONE as a technical consultant.

Advertisements

Author: Victor Vogelpoel

Dad, SharePoint technical specialist, PowerShell architect, photographer and just a guy whose life happens while trying planning it.

One thought on “Putting PowerShell to good use: discovering the OpenText eDOCS COM API

  1. Pingback: Putting PowerShell to good use: discovering the OpenText eDOCS WCF API | Victor Vogelpoel

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s