1. Purpose
2. DRD, DRD Processor and DRS
3. DRD and Hummingbird DM
4. DRD and DAI/DOCS Open
5. General Structure
6. Used File Types
7. Options
8. Actions
9. Variables
10. DMS specific variables
11. Rights (Hummingbird_DM specific)
12. Known tags
13. Notes
14. Revision History
15. Contact Information

Purpose

The DRD interface is a common way to describe Document Related Data. The main aim is to provide all metadata information, security, options and file links.

This interface is considered to be open to any Document Management System (DMS).

The DRD information itself does NOT contain the document file(s) itself. However the DRD and document file can be combined into an XML or ZIP. All these variants should be processable by a component that can process DRD and DRS.

DRD, DRD Processor and DRS

The DRD definition does only contain and provide data. DRD does not contain any processing instructions (as known from the DAI interface). Data and script should be strictly separated to prevent from macro viruses as they exist in the data/document files of Microsoft Office products for example. Processing is usually done with applications and/or scripts. To simplify document related processings the Document Related Script language definition has been created to enable an administrator (who has less experience on programming and scripting) to define and configure document related processings. Documentation to the DRS definition is available as enhancement module to the Simple Batch Language (which is based on the Application Control Script component).

The DRD Processor application is a tool that simplifies batch processing of folders containing DRD files to process or other files to import performing specified DRS scripts on the found files. It includes error handling and a status query tool. The DRD Processor comes along with the DRS interpreter that allows running any document related script.

DRD and Hummingbird DM

As the Hummingbird DM API is very rough the Hummingbird DM cover interface from MAY Computer (implemented via wmHDMI.dll) provides a more easier to use interface that further integrates the DRD interface so that you can process DRD files against Hummingbird DM. When using DRS there is usually no need to touch the HDMI interface itself.

DRD and DAI/DOCS Open

DRD and DRS are the new formats replacing the older DAI format. However there is currently no DRD or DRS interface implemented to work with DOCS Open and in the near future there will be no attempt to implement this. DRD and DRS are more common than DAI which mainly sticks to DOCS Open.

General Structure

BEGIN DRD
  ;Options
  BEGIN OPT
    {<OptionName>=["]<OptionValue>["]}
  [END [OPT]]
  ;User variables
  BEGIN VAR
    {<VariableName>=["]<Value>["]}
  [END [VAR]]
  ;Profile fields
  BEGIN PRF
    {<ProfileFieldName>=["]<ProfileFieldValue>["]}
  [END [PRF]]
  ;Security items
  BEGIN SEC
    {usr.|grp.<UserOrGroupID>=["]<Rights>["]}
  [END [SEC]]
  ;Component items (versions, attachments)
  BEGIN CMP
    {<ComponentID>=["]<FileName>["]}
  [END [CMP]]
  ;History entries
  BEGIN HST
    {<ShortName>=<Description>[;RELDOC=<DocumentID>]}
  [END [HST]]
  BEGIN LOG
    {yyyy-mm-dd hh:nn:ss=<Description>}
  [END [LOG]]
END DRD

<UserOrGroupID> ::= %AUTHOR%|%TYPIST%|%DMSUSER%|%DMSGROUP%|<GroupID>|<UserID>

As alternative to the structure above you can work without BEGIN ... and END ... by specifying the appropriate prefixes as shown below:

BEGIN DRD
{OPT.<OptionName>=["]<OptionValue>["]}
{VAR.<VariableName>=["]<Value>["]}
{PRF.<ProfileFieldName>=["]<ProfileFieldValue>["]}
{SEC.usr.|SEC.grp.<UserOrGroupID>=["]<Right>{,<Right>}["]}
{CMP.<ComponentID>=["]<FileName>["]}
{HST.<ShortName>=<Description>}
{LOG.yyyy-mm-dd hh:nn:ss=<Description>}

END DRD

In the second alternative (which can even be mixed with the first variant) you do not need to maintain the order OPT, VAR PRF, SEC, CMP, HST. However if a DRD is saved using the activex interface it is always written in the first form.

Used File Types

Extension	File Type Description
DRD	Document Related Data File containing document metadata and maybe file information.
DRS	Document Related Script SiBaLa script using language enhancements for document related processing.
DRX	Document Related XML XML file containing DRD info and maybe document file.
DRZ	Document Related ZIP ZIP file containing DRD and maybe document file.

Options

All options are generally optional but to identify the related document at least one of the options DocFile or DocID must be set.

Option	Description
DocFile=<Filename>	Sets the filename of the main document file that is imported (if applicable).
DocID=[<Library>-#]<DocNr>[-v<VersionLabel>]	Identifies a specific existing document (an alternative to this is specifying Lib, DocNr and Version options).
Lib=<Library>	Library/store name.
DocNr=<DocNr>	Document number.
Version=<VersionNr>|<VersionLabel>	Version number or label of the addressed document.
DMS=HUMMINGBIRD_DM|EDAS|DOCSOPEN|OTHER	Source/Destination DMS
Action=<Action>	Desired document action to perform. Details on available actions see Actions.
Creator=<UserID>	User ID of creator of this DRD. This option is added automatically on DRD save if missing. Used also as version author when adding components.
CreatorsWS=<HostName>	Workstation name where this DRD has been created. This option is added automatically on DRD save if missing.
Editor=<UserID>	User ID of person who edited/saved the DRD lately. This option is updated automatically on DRD save. Used also as version typist when adding components.
EditorsWS=<HostName>	Workstation name where this DRD has been saved from lately. This option is updated automatically on DRD save.
RouteInfo={[<UserID>;<HostName>]}	List of user ID's and workstation names who worked on this DRD. This option is updated automatically on DRD save.
Silent=1|0	Directive if operations should be performed silently if possible and if there can be choosen a silent operation. Default is 1.
UpdateDoc=1|0	If 0 then document file will not be updated otherwise document file (DocFile option) will be uploaded if the option is set in DRD. Default is 1.
ExportAllComponents=0|1	For retrieve and export actions this option specifies if only the current/specified version should be retrieved/exported or if all components (versions) should be retrieved/exported. Default is 0 (export current/specified version only).
ExportPath=<Path>[\<FileNameTemplate>]	For export actions this option defines the destination path and filename template for the destination file(s) of the document components. Available are all DRD variables.
OriLib=<Library>	Read only and only available if a document has been retrieved - Library/store name of the read document.
OriDocNr=<DocNr>	Read only and only available if a document has been retrieved - Document number of the read document.
OriDocFile=<Filename>	Read only and only available if a document has been retrieved - Network filename of the read document.
OriVersion=<VersionNr>|<VersionLabel>	Read only and only available if a document has been retrieved - Current version of the read document.
OriVersions=<NumberOfVersions>	Read only and only available if a document has been retrieved - number of versions of the read document.
NewLib=<Library>	Read only and only available if a document has been saved as a new version or document - New Library.
NewDocNr=<DocNr>	Read only and only available if a document has been checked in with the NEWVER or NEWDOC directive or has been saved as a new version or document - New docnumber.
NewVersion=<Version>	Read only and only available if a document has been checked in with the NEWVER or NEWDOC directive or has been saved as a new version or document  - New version.
EMail=<E-Mail-Address>{;<E-Mail-Address>}	One or more e-mail addresses where email should be sent to. This is a reserved property that may be interpreted by a script dealing with the DRD (DRD, DRD Processor, ...).
Purpose=<Purpose>	Reserved property for specifying a purpose keyword which probably is interpreted by a script dealing with the DRD (DRS, DRD Processor, ...).
Comments=<Comments>	Comments regarding DRD source/destination/workflow etc. - This option is also used as version comments when adding components.
SelectedDocuments=[<DocID>{;<DocID}]	Return value of SELECTDOCUMENTS action containing a list of selected documents.
LinkFileFormat=<FileExtension>	Usually DMS option is taken to decide in which format a link file should be generated in. This option overrules DMS setting.
URLFormat=<URLStringWithVariables>	Usually DMS option is taken to decide the how to build a document URL. This option overrules DMS setting and uses the URL specified by replacing DRD %-variables with the appropriate values.
===== HUMMINGBIRD_DM specific options	Currently only applies to Hummingbird DM
UnsecureDoc=0|1	If 1 then document is unsecured (security flag is removed). Default is 0 which means that the flag is not changed if no security items are in the DRD. If security is set in the DRD then the security flag will be set.
RemoveTrustees=0|1	If 1 Remove all trustees/security items from the document. Default is 0.
Public=0|1	Only for folders/projects (APP_ID=FOLDER). If 1 then the folder is added to the public folders on the desktop.
ParentFolders=[(+|-)][<Library>-#]<DocumentNumber>|<FolderPath> {;[(+|-)][<Library>-#]<DocumentNumber>|<FolderPath>}	If specified then the document will be added to the folder/project with the specified document number (document and folder must be in the same library). The document is removed from other folders/projects not in the list except if you are always using (+) and (-) prefixes. In that case the specified folder links are added or removed without touching existing links. Path separator in <FolderPath> is "\" (Backslash).
RelatedItems=[(+|-)][<Library>-#]<DocumentNumber> {;[(+|-)][<Library>-#]<DocumentNumber>}	If specified then the specified documents/folders will be added to related document list(related items must be in the same library). Relations not in the list are released except if you are always using (+) and (-) prefixes. In that case the specified relations are added or removed without touching existing relations.
FormName=<DMProfileForm>	If specified then on imports the specified form is used instead of default ProfileForm specified in wmHDMI.ini. For updates you can use "<none>" or "<default>" to reset used form to default.
AllowEdits=0|1	Flag if profiles can be edited. Default is 1.
SafetyMode=0|1	If SavetyMode is explicitely set to 0 then profile updates are performed also if documents are set to read-only. (Read-Only status is then temporarily removed.)
UsedSections=<SectionList>	Performance related option. If not empty then only specified sections of the DRD are taken into consideration when processing against DMS (on RETRIEVE, IMPORT, UPDATE and EXPORT operations). <SectionList> must be a comma separated list of DRD sections (PRF,SEC,CMP,HST).
===== DOCSOPEN specific options	Only applies to DOCS OPEN (for backward compatibility and to accomplish a smooth move from DAI to DRD/DRS.).
IncludeDAIsBefore=<DAIFilename>{;<DAIFilename>}	List of DAI files to include before translating the DRD to DAI. Equivalent to a First.dai of DAI Processor.
IncludeDAIsAfter=<DAIFilename>{;<DAIFilename>}	List of DAI files to include after translating the DRD to DAI. Equivalent to a Last.dai of DAI Processor.

Actions

The following values are known for the Action option (OPT.Action):

Action	Description
IMPORT	Create new document from given DRD.
UPDATE	Update existing document.
RETRIEVE	Load existing document's data into DRD (with link to appropriate files on the document server if available).
EXPORT	Export existing document with the appropriate files to a desired location. Usually requires the ExportPath option set to the appropriate directory or filename template. If filename template is missing usually %DOCID%-v%VERSION%-%TITLE%.%FILEEXT% is assumed.
SEARCH	Search for documents with the given criteria (PRF section data is assumed to be the search criteria).
CHECKOUT	Get document copy and lock the document. Usually requires the ExportPath option set to the appropriate directory or filename template. If filename template is missing usually %DOCID%-v%VERSION%-%TITLE%.%FILEEXT% is assumed.
CHECKIN	Update and unlock the document. Usually requires the ExportPath option set to the appropriate directory or filename template. If filename template is missing usually %DOCID%-v%VERSION%-%TITLE%.%FILEEXT% is assumed. For checkin if the ExportPath property is missing the DocFile option property is assumed to point to the location of the document file that should be uploaded to DMS. Specifying NEW or NEWSUB in Version option causes checkin of the file as a new version (DMS specific).
LOCK	Lock document (without getting a copy of the document file).
UNLOCK	Unlock document (without checking in a file).
EDIT|OPEN	Open document for editing in the associated application.
[PRE]VIEW	Preview document (in preview application or window; if available).
PRINT	Pring document
SHOWPROFILE	Show profile form (meta data information) of the document
SHOWHISTORY	Show history/activity log for the document
SHOWSECURITY	Show security/permissions for the document.
MAILDOC	Mail document file. If EMail option is set then operation should be performed silently if the Silent option is set.
MAILREF	Mail document reference. If EMail option is set then operation should be performed silently if the Silent option is set.
DELETEDOCUMENT	Delete the document specified in DRD options.
DELETEVERSION	Delete a specific version of a document as specified in DRD options.
EDITSEARCHCRITERIA	Show search form to enter/edit search criteria. The search criteria is stored in the PRF section of the DRD.
SELECTDOCUMENT	Let the user choose a document (by providing possibility to search for a single document and select one from a search result list).
SELECTDOCUMENTS	Let the user choose one or more documents (by providing possibility to search for a document and select one or more from a search result list). After this action the option SelectedDocuments is set to a ";" separated list of document ids that were selected by the user.
===== HUMMINGBIRD_DM specific actions
MAKEREADONLY	Set document to readonly status for the document.
REMOVEREADONLY	Remove read only status for the document.
ADDTOATTACHE	Add document to Attache.
REMOVEFROMATTACHE	Remove document from Attache.
EDITPROFILE	Unlike ShowProfile this action edits a profile without saving any document.

Note: However if you are processing a DRD with a DRS against another DMS the DRS integration module for that DMS may have implemented further but even less actions than listed here.

Variables

Variable	Description
%LIB%	Library/Store name
%DOCNR%	Document number
%VERSION%	Version number or label
%TITLE%	Title/Document name
%DOCID%	Document identifier (= %LIB%-#%DOCNR%)
%DOCIDLONG%	Document identifier with version and title (= %LIB%-#%DOCNR%-v%VERSION%-%TITLE%
%DRDFILE%|%DRDFULLNAME%	Filename of current DRD file (if available).
%DRDFULLPATH%	Full path to current DRD file (if available).
%DRDPATH%	Path to current DRD file (without drive information and with leading backslash - if available).
%DRDEXT%	File extension of current DRD file (usually "DRD" - if available).
%DRDFILENAME%	Filename (without path) of current DRD file (if available).
%DRDFNAME%	Filename without extension (and without path) of current DRD file (if available).
%DRDFILEDATE%	File date of current DRD file (if available) in default date format (from control panel settings).
%DRDFILETIME%	File time of current DRD file  (if available)in default time format (from control panel settings).
%DRDFILEISODATE%	File date of current DRD file (if available) in ISO format (yyyy-mm-dd).
%DRDFILEISOTIME%	File time of current DRD file (if available) in ISO format (hh:nn:ss).
%DRDFILEDATE:<Format>%	File date/time of current DRD file (if available) in specified format (use abbrevations shown above or see application script date and time formats).
%DRDINDEX%	Index of current DRD in open DRD file (if available).
%DRDCOUNT%	Index of current DRD in open DRD file (if available).
%DOCFILE%|%DOCFULLNAME%|%DOCUNCNAME%	Full filename of document file
%DOCFULLPATH%	Fullpath (but without filename) of the document file
%DOCPATH%	Path (without drive or share name) of the document file
%DOCFILEEXT%|%DOCEXT%	File extension of document file (use %FILEEXT% in export paths)
%DOCFILENAME%	Filename (without path) of document file
%DOCFNAME%	Filename (without path and extension) of document file
%DOCFILEDATE%	File date of document file in short format
%DOCFILETIME%	File time of document file in short format
%DOCFILEISODATE%	File date of document file in ISO format (yyyy-mm-dd)
%DOCFILEISOTIME%	File time of document file in ISO format (hh:nn:ss)
%DOCFILEDATE:<Format>%	File date/time of current DRD document file in specified format (use abbrevations shown above or see application script date and time formats).
%DIR<Index>%	n. subfolder in current DRD document file path. For a document file C:\Poll\Dept01\TestDoc.doc %DIR1% results in "C:".
%LASTDIR<Index>%	n. subfolder in current DRD document file path but counted from last/deepest subfolder. For a document file C:\Poll\Dept01\TestDoc.doc %LASTDIR1% results in "Dept01".
%OPT.<OptionName>%	Value of appropriate option (OPT section)
%VAR.<VariableName>%	Value of appropriate user variable (VAR section)
%VAR.ORI.<ProfileFieldName>%	Value of appropriate original profile field (VAR section) before an update is performed. Only available on update operations where the original profile field values are loaded to the VAR section with the "ORI." prefix.
%PRF.<ProfileFieldName>%	Value of appropriate profile field (PRF section)
%SEC.<Type>.<Name>%	Appropriate security entry (Type=usr|grp; SEC section)
%CMP.<VersionLabel>%	Appropriate component entry (CMP section)
%HST.<EntryID>%	Appropriate history entry line (HST section)
%TAG.<TagName>%	Appropriate (DMS specific) tag. Tags are always temporary added by software dealing with DRD and the values are not saved along with the DRD item.

DMS specific variables

Usually DMS specific and resolved at processing against DMS only:

Variable	Description
%DMSUSER%	Current user in DMS.
%DMSGROUP%	Primary group of current DMS user (HUMMINGBIRD_DM specific).
%CURRENTLIB[RARY]%	Current library/store of DMS.
%PRIMARYLIB[RARY]%	Primary library/store of DMS.
%WORKLIB[RARY]%	Work library/store of DMS.
%ERRORS%	Number of errors occured in DMS.
%WARNINGS%	Number of warnings occured in DMS.
%ERRORMSG%	Error(s) message(s) from DMS.
%WARNINGMSG%	Warning(s) message(s) from DMS.

Rights (Hummingbird_DM specific)

Right keyword	Value	Description
PROFILE_VIEW | VIEW_PROFILE	1	Allow profile view
PROFILE_EDIT | EDIT_PROFILE	2	Allow profile edit
DOCUMENT_VIEW | VIEW_DOCUMENT	4	Allow document view
DOCUMENT_RETRIEVE | RETRIEVE_DOCUMENT	8	Allow document retrieve
DOCUMENT_EDIT | EDIT_DOCUMENT	16	Allow document edit
DOCUMENT_COPY | COPY_DOCUMENT	32	Allow document copy
DOCUMENT_DELETE | DELETE_DOCUMENT | DELETE	64	Allow document delete
DOCUMENT_CONTROL | ACCESS_CONTROL | CONTROL_DOCUMENT | CONTROL_ACCESS	128	Allow security/access control list edit
PUBLISHED_ONLY | ONLY_PUBLISHED	512	Access to published version only
NONE | NOTHING	0	No rights
READ | READONLY	45	Allow read only rights (=1 + 4 + 8 + 32)
PROFEDIT	47	Allow read only + profile edit rights (=1 + 2 + 4 + 8 + 32)
EDIT	63	Allow edit rights, but no delete and no access control (=1 + 2 + 4 + 8 + 16 + 32)
ALL | FULL	255	Allow full control/access
REMOVE[RIGHTS]	-1	Remove person or group from trustee list
DENY_PROFILE_VIEW | DENY_VIEW_PROFILE		Deny profile view
DENY_PROFILE_EDIT | DENY_EDIT_PROFILE		Deny profile edit
DENY_DOCUMENT_VIEW | DENY_VIEW_DOCUMENT		Deny document view
DENY_DOCUMENT_RETRIEVE | DENY_RETRIEVE_DOCUMENT		Deny document retrieve
DENY_DOCUMENT_EDIT | DENY_EDIT_DOCUMENT		Deny document edit
DENY_DOCUMENT_COPY | DENY_COPY_DOCUMENT		Deny document copy
DENY_DOCUMENT_DELETE | DENY_DELETE_DOCUMENT | DENY_DELETE		Deny document delete
DENY_DOCUMENT_CONTROL | DENY_ACCESS_CONTROL | DENY_CONTROL_DOCUMENT | DENY_CONTROL_ACCESS		Deny security/access control list edit
DENY_READ | DENY_READONLY		Deny read only rights
DENY_PROFEDIT		Deny read only and profile edit rights
DENY_EDIT		Deny edit rights (deny edit profile, edit document, document delete, deny access control)

Known tags

Tag name	Description
DocumentsFound	After a SEARCH action the tag holds the number of found documents. Used while looping through found documents.
LastFetchedItem	After a SEARCH action the tag holds the last fetched document. Used while looping through found documents.

Notes

Attachment labels in Hummingbird DM can not be longer than 3 characters.

Activity descriptions (history entries) in Hummingbird DM can not be longer than 20 characters.

Why not XML? - The DRD can be embedded in XML together with the appropriate document(s). DRD itself is not xml because this way it is better readable in plain ASCII text editors. Further in the attempt to get maximum performance using an XML parser would slow down the process. However there will be a definition for DRD in XML equivalent format in the future.

Revision History

Contact Information

Technical support and latest information on our products are available at http://support.may.co.at

E-Mail support: mailto:support@may.co.at

MAY Computer GmbH & Co KG
Microsoft Solution Provider
Galvanigasse 2
A-1210 Vienna / Austria
Tel.: +43/1/278 20 80 Fax: +43/1/278 20 80 /22
http://www.may.co.at
mailto:may@may.co.at