dqMan requires a valid license for the application to work. Customers having purchased dqMan (or having requested a 14-day trial license) will receive their license key(s) via email.

dqMan can be activated easily online where it automatically verifies the license key against the dqMan license server, but for machines which are permanently offline/isolated from the internet an offline license activation method is also available.

Online License Activation

1. Start dqMan

2. The dqMan License Activation dialog opens prompting the user to enter a license key

3. Copy & paste the license key from the email you have received after purchasing dqMan (or having requested a trial license)

4. Press the Activate Online button
5. dqMan validates the license key entered at step 3 and the main application window opens

If the activation could not be completed successfully or the license is expired or disabled, dqMan will display an appropriate error message. The user can retry entering a valid license, or click any of the links on the above dialog to help solving any potential issues with license activation.

Offline License Activation

To activate dqMan on a machine which is permanently offline/isolated from the internet follow the steps below:

1. Go to https://dqman.com/offline-license

2. Enter the email address used to purchase dqMan as well as the license key you want to activate offline. The email address is used to authenticate the owner of that mailbox as a dqMan customer/license holder, therefore only email addresses used previously for purchasing dqMan can be used here. If you do not own or have access to the mailbox used to purchase dqMan you will need to contact the owner of that mailbox and have them perform this procedure themselves, or have them forward the resulting email to you before continuing with step 4.
3. Press the Request Offline License Now button

4. You will receive an email shortly with a dqMan offline license file (*.dqman file) attached

5. Use your company intranet to transfer the offline license file received in the previous step to the offline machine where dqMan is installed

6. Start dqMan

7. The dqMan License Activation dialog opens prompting the user to enter a license key

8. Press the Activate Offline button, there is no need to enter the license key in this case
9. dqMan opens a standard File Open dialog

10. Locate the offline license file from step 5 and Open it

11. dqMan validates the license from the offline license file and the main dqMan window opens

If the activation could not be completed successfully or the license is expired or disabled, dqMan will display an appropriate error message. The user can retry opening another license file, or click any of the links on the above dialog to help solving any potential issues with license activation.

Viewing information about the current license in dqMan

To verify/view the license dqMan is currently using, just open the About dialog from the dqMan main window's Help menu. The License Information section at the bottom of the About dialog displays information about the dqMan license such as the license key, license expiration date and license type (e.g. 1/2/3-Year subscription or 14-day trial).

It is also possible to Change License Key here in case this would be necessary.

Notifications

dqMan will display notifications 30, 14 and 1 day(s) respectively before the current license expires so the user can take action (renew/purchase) in due time before the license actually expires causing dqMan to stop working.

Simply click OK to acknowledge the message and continue working with dqMan.

License Expiration

Either of the#online-license-activation or#offline-license-activation methods described above can be used to reactivate dqMan with a valid license, after which the application will resume working normally.

22.2

Features

• Offline license activation (see #offline-license-activation)

• Option to change current license (#viewing-information-about-the-current-license-in-dqman)

• Command line tools dqDQL and dqAPI for executing DQL and API Scripts called from shell scripts/batch files

• Code folding/collapsing/outlining in DQL Editor

• Refactored DQL code parser (improved syntax highlighter, auto-complete)

• Copying code from dqMan preserves syntax highlight colors when pasted into applications supporting HTML text (Microsoft Office, webapps in webbrowser, etc.) - useful for emailing or documenting code while maintaining easy readability due to syntax coloring

• Custom tab colors for highlighting/marking individual tabs

• Session functions for flushing the various cache types (main menu Functions/Flush Caches)

• Edit Java and DFC paths directly in the UI in case the auto-detect algorithm fails to detect some of the required prerequisites' locations on first start

Improvements, Changes

• Improved Script Editor to automatically jump to where the script got paused during execution (having been manually being paused, hitting an error or reaching a breakpoint)

• Improved Script Editor to detect the script type (DQL/API) when scripts are dropped into the editor (prevously this only worked for scripts opened directly from Script Navigator)

• Improved column auto-spacing for Connections Panel in Object Navigator

• Improved performance when saving/loading (very large) queries to session user history

• Improved/changed navigation in History Panel to be consistent with currently active history item and History Back/Next buttons in the main toolbar

• Improved Favorites and Session/Object Functions lists to display an additional column stating the source of the respective item (Default, User or Shared configuration file)

• Improved Favorites and Session/Object Functions lists to also be able to export Shared items when using Export to File

• improvements to auto-complete of dqMan user defined API variables when the cursor is between %...% characters in API Script Editor, Generate Script (API mode), API code in Object/Session Functions

• Improved UI light/dark themes' consistency across various user interface elements where theme specific colors did not exist previously or were not always applied correctly (certain texts, scrollbars, grids, highlight colors etc.)

• Improved DFC auto-detection when dqMan is deployed directly on a Content Server machine

• Improved description and organisation of Result Grid/Data Grid context menu item Mark Lines and its submenu items to make the intended purpose and usage of these commands less ambiguous

• Consolidated dqMan translation and identifier definitions to dedicated configuration files dqManTranslations.xml and dqManIdentifiers.xml. Previously these elements could be defined in multiple existing configuration files, often containing redundant information. User editable templates of these files are also provided in the %appdata%\dqMan\config folder

Fixes

• Fixed issue where the Jobs window would behave inconsistently when refreshing, sometimes resetting the state of all the controls to default

• Fixed issue with slow refresh (several seconds) of Jobs window

• Fixed issue with scripts using *nix/LF type line endings

• Fixed CSV export from Results Grid failing to export non-latin characters correctly to the resulting file

• Fixed issue with script files opened from Script Navigator displaying only the first line immediately after having been loaded

• Fixed issue where dumping another object from an already opened dump window threw an error saying the object was not accessible, despite the dump being performed and the data being displayed correctly

• Fixed some scaling issues when using multiple monitors having different scaling settings and moving dqman dialogs between them

• Fixed issue where copying and pasting a value from the Result Grid into the DQL Editor inserted a new line after the value

• Fixed an issue where changes to a license on the server were not registered by dqMan

• Fixed an issue where dqMan was unable to save the session query history files if the Documentum user name contained characters which Windows did not allow to be used in filenames

• Fixed an issue where searching in the History Panel would automatically add unwanted partial search terms to the search history as the user was typing the search terms

• Fixed issue where the History Panel list/scrollbar could get "stuck" to the mouse cursor following and reacting to the cursor's movements even though the cursor was elsewhere in the application

• Fixed issue where trying to Search in the Compare Objects window threw an access violation error

• Fixed issue with the Script Editor where dragging and dropping a script file would throw an error unless the Script Navigator had been opened previously

• Fixed DQL Editor throwing "Missing right parenthesis for statement Options" error in some cases when running queries containing template fields

• Fixed non-working Go To dialog opened from Result Grid header row context menu item "..."

• Fixed issue where the Favorites tree in the Repository Navigator would get populated with the same Favorites items more than once

• Fixed 2 crashes that could occur while the dqMan process was loaded in memory at addresses above the 4GB range (triggered by right-click action in Script Log window and spinner control in Import from File/Clipboard dialog)

Once logged in, you can work in the Session Window in any of the following editors/views:

• DQL: DQL code editor/view

• API: API command view

• DQL Script: DQL script editor/view

• API Script: API script editor/view

You can switch anytime between these views using the above toolbar buttons or the View menu. Changing the view does not delete any existing commands or results in other views; moreover, during script debugging, you can execute commands in other views without stopping the debug process.

You can use the below toolbar buttons to execute your DQL queries/API commands/scripts. It is possible to run/step into/pause/stop DQL queries/API commands/scripts.

dqMan comes with a profile management feature allowing users to define multiple profiles using different Java and DFC versions.

This can be used by Documentum professionals who need to work with many different Documentum Content Server versions/environments while using just one dqMan installation.

dqMan can be started with any profile, thus providing the respective Java and DFC environment for working with specific Documentum Content Servers.

Managing Profiles

Profiles can be created, edited and deleted using the JRE & DFC Profiles page in the dqMan Options dialog (Extras menu>Options)

On the first launch after deployment dqMan will attempt to auto-detect the default Java and DFC installations present on the maching and if this is successful, it will create a profile called [0] Default. To make sure that dqMan will be able to correctly auto-detect the Java and DFC installations on the local machine please follow the instructions in #prerequisites.

Loading Profiles

dqMan can be launched with any of the available profiles. It is also possible to run multiple dqMan instances using different profiles.

The recommended way for using profiles is to create custom dqMan shortcuts, with each shortcut used to load a specific profile:

1. Hold Alt & drag dqman.exe from your dqMan folder to the Desktop to create a shortcut

2. Rename the shortcut to something suggestive

3. Edit the shortcut's properties and append either of the following to the command line in the shortcut's Target field:

To confirm the expected profile has been loaded, open Help>About and verify the profile name and Java and DFC information in the About window's System information section.

Troubleshooting profiles and editing the dqman.properties file

dqMan saves all profile related information to the %localappdata%\dqMan\Config\dqman.properties file. Although it is not recommended to edit this file directly, it may be required to do so in certain situations.

dqMan fails to detect locally installed Java and/or DFC

if dqMan fails to automatically detect the default Java and/or DFC installed on the local machine it is usually due to either of these not having been installed as per their respective vendor's installation instructions, as outlined in #prerequisites. We recommend following the instructions from the Prerequisites page and then restarting dqMan to allow it to correctly detect the default Java and/or DFC installations.

If it still isn't possible for dqMan to detect the default Java and/or DFC installations despite having followed the instructions outlined in #prerequisites it may be necessary to edit or create the dqman.properties file manually. Please follow the below steps to edit/create the file manually:

1. Open the %localappdata%\dqMan\Config\dqman.properties file with your text editor If the file does not exist, create a new file in your text editor and save it as %localappdata%\dqMan\Config\dqman.properties

2. Copy and paste the template dqman.properties file's content from #template-for-dqman.properties-fileinto the text editor

3. Edit the paths from the template to match your Java and DFC installations

4. Save the dqman.properties file and start dqMan

The default Java and/or DFC detected initially by dqMan has been removed/uninstalled later and now dqMan cannot start

If the Java and/or DFC auto-detected during dqMan's first start is later removed/uninstalled then dqMan will run into errors as it won't find the required prerequisites anymore. To reset dqMan's default profile and re-trigger dqMan's auto-detect functionality, follow the steps below:

1. Open the %localappdata%\dqMan\Config\dqman.properties file with your text editor

2. Delete all lines starting withdqman.profile.....[0]= (pay attention at the [0] (zero) index and do not delete other lines containing non-zero indices)

3. Save the file and start dqMan dqMan should now auto-detect your newly installed Java and/or DFC instead of the previously uninstalled versions

4. If step 3. fails, fall back to #dqman-fails-to-detect-locally-installed-java-and-or-dfc above

Template for dqman.properties file

Use the below template to create a new dqman.properties file if needed.

dqman.profile.name[0]=Default dqman.profile.path.jre[0]=C:\Program Files\openjdk-11.0.14 dqman.profile.path.dfc.program[0]=C:\Program Files\Documentum dqman.profile.path.dfc.user[0]=C:\Documentum

dqMan is powerful and feature-rich administration tool for OpenText Documentum.

It offers many Documentum administrative features and functionalities, DQL and API support for single queries/commands as well as extensive code editing and script execution/debugging features, script templates for generating scripts, job management, import/export from/to external data sources, and much more.

The clean user interface allows quick and efficient use of all these features and in addition offers extensive customization with context sensitive actions based on Documentum DQL and API languages (no 3rd party or proprietary scripting languages needed).

dqMan offers a wide range of functionalities for OpenText Documentum professionals (administrators, consultants, developers) to manage OpenText Documentum Content Servers.

Send any feedback, questions, feature requests or bug reports to dqman@fme.de.

Prerequisites

Operating system:

Microsoft® Windows® version 10 or later (64-bit only, 32-bit versions are not supported!)

OpenText Documentum Foundation Classes (DFC):

Documentum 16.4 - 16.7 requires DFC 16.4 with latest patch - DFC 16.7

Documentum 20.x - 22.x requires DFC 20.x - DFC 22.x

Java:

Oracle Java SE JDK or supported OpenJDKs (64-bit only, 32-bit versions are not supported!)

all versions officially supported by the target Documentum Content Server version and DFC

Install dqMan

dqMan is distributed as a portable application packaged as a ZIP file. The ZIP file can be extracted anywhere on the installation machine. The folder where dqMan is extracted to can have any name, as per the user's preferences.

Please note that deploying the application to the default Program Files folder may require administrative permissions; this is standard Windows behavior when deploying any files to the Program Files folder and not specific to dqMan.

Command line parameters

You can use the following command line parameters in dqMan:

For login:

• -r<Repository>- Autoconnect to the supplied repository. The repository name must be given in the same format dqMan is configured to use. If fully qualified server names are activated, repository names need to match this format.

• -u<Username> - A valid username to log in with

• -p<Password> - The password for the user.

Profile management:

• -profile <index|name> - Start dqMan with a custom Java & DFC profile by specifying a profile index number or profile name

Other parameters:

• -f<Filename> - The full name (including path) to a scriptfile can be supplied to open this at startup. The scripttype (API or DQL) is determined by the file extension. If the filename contains spaces, it must be enclosed by double quotes”.

• -execute - If a file is loaded using –f<filename>, it can be executed immediately. This function also needs valid login informations passed with the command line.

  When the execution is finished, dqMan will be closed.

Glossary and Terms

Log in/out

To log in to a Documentum Content Server, start dqMan, enter your login credentials and then select the desired repository from the list. You can save your login credentials by selecting Save in login history and use them again in the future by clicking the History button.

Manage Sessions

dqMan can open multiple sessions to the same or different repositories. You can open a session in several ways:

• Click Session menu>New Session Window, or press Ctrl+N.

• Click the New Session Window toolbar button

• If you already have an open Session window which you would like to duplicate into a second session with the same credentials on the same repository click the Copy session toolbar button

• Certain API commands can be executed without a connected session (such as getservermap, getdocbrokermap or connect).

Whenever a session is needed but not available, the same login dialog box described in #2.1-log-in-out is displayed.

Sessions are always bound to a session window. Disconnecting a session window will terminate the session, but will not close the session window.

dqMan enables you to open as many sessions as needed, restricted only by the settings in the Client or Server configuration.

You can manage Sessions using the Session menu or the toolbar. The available functions are:

In API View, you can execute API commands.

To execute an API command, do any of the following:

• Press Enter

• Press F9

• Press Shift+Enter

• In the Edit menu, select Run

• Click the Run button on the toolbar.

Double-click an element in the result log to copy the value to the clipboard. Press Ctrl when double-clicking to paste the value into the active input control at the current cursor position.

Click and hold the left mouse button for 1 second on any value representing a valid Documentum r_object_id to load the respective object into the Object Navigator (see Object Navigator)

Certain API commands can be executed without a connected session (such as getservermap, getdocbrokermap or connect).

To open the API command help, click the API Command Help button to the right of the Command field. You can then search for API commands or you can insert a command by double-clicking the command input field.

The context menu of the result log contains some additional functionality:

dqMan has a globally available search functionality which can be used in most any place where text is presented to the user in some form (any type of code or script editor, object dump, tables/grids, logs/command output messages, text files opened for viewing inside dqMan, etc.)

1. Click Edit menu>Find (or press Ctrl+F) or Find next (or press F3).

2. Enter the desired search parameters in the Search for dialog box or select one from the list. Select whether the search items must be Case sensitive and whether you want to run search across Rows or Columns.

3. Click Search. To count all occurrences, click Count.

You can create a dump from almost every control where a validr_object_id is displayed and highlighted or selected.

In such cases you can call the Dump object function from the appropriate context menu on the r_object_id. The dump will be opened in a separate window.

Dump object from Clipboard If the clipboard contains a valid r_object_id, you can generate a dump directly by clicking Extras menu>Dump Object from Clipboard function or by pressing Alt+D. If a valid session is not found, first the login history will be searched and, in case of success, an automatic login is established. If no session can be found or the automatic login fails, the login dialog box will be displayed.

Click and hold the left mouse button for 1 second on any value representing a valid Documentum r_object_id to load the respective object into the Object Navigator (see )

In the DQL View, you can execute single DQL queries.

To execute a DQL query, do one of the following:

• Press F9 or Shift+Enter.

• Go to the Edit menu>Run.

• Click Run on the context menu.

• Click the Run button on the toolbar.

Other actions you can perform in the DQL View:

• Double-click a cell in the result grid to copy the value on the clipboard. Press Ctrl when double-clicking to insert the cell value into the code editor at the current cursor position. The latter can also be performed on the result grid's column headers to insert the respective column names as attribute names at the cursor position.

• Double-click the messages in the status bar to copy them to the clipboard. Move the mouse cursor over the status bar to display the current message in a tooltip, if it does not fit into the message bar area.

• You can see information about the latest executed action and the query result in the Messages area.

The status bar displays the complete execution time of the query, including the transfer of the query results to dqMan. The pure server response time without data transfer is labeled as Server response time.

Work with DQL Queries

You can enter one or several DQL queries in the SQL Query input area. When executing the query, all the content in the input area is regarded as one query and transferred to the Documentum server for execution. However, if only a part of a query is selected, then only this part is executed.

Use semicolons as separators for two or more queries. Setting the text cursor on one query selects this query for execution.

Moreover, you can add comments. Every line beginning with the # or // characters is regarded as a comment line.

Syntax assistance

A number of syntax assistance functions supports the creation of DQL queries:

• Command syntax: Click a DQL command and wait for the hint to view the correct command syntax.

• Function syntax: The syntax of functions, such as Dateadd, Datediff and so on, is displayed automatically while typing the DQL command. You can activate syntax assistance by pressing F1 on your keyboard.

• Auto completion: Several dynamic values, such as object names, group names and so on, or allowed function values are faded in automatically in the form of a selection list. You can copy the values from selection lists by pressing Enter.

You can manually activate the selection list anywhere in the command area by pressing Ctrl+Space. The list is filled context dependent with the likely values at the current position. If none of the pre-defined lists applies, the list is filled with the possible attribute names.

Some of the selection lists are read dynamically from the repository when opening the session. The values in these lists can be subject to changes by other activities that will not be recognized by dqMan. In this case, you can reload and refresh the lists by clicking Session menu>Refresh Valuelists.

Query by Label

In the DQL View, you can use queries the attribute labels of any locale instead of the original attribute name. dqMan will replace labels with the attribute names at execution. Attribute labels must be placed in square brackets within the query.

Select r_object_id,object_name,[ACL Name],[Application type] from dm_document where …

The Results list

The Results list contains the results of the DQL queries.

Use your mouse to resize the columns and rows and reposition the columns in the Results list.

To search through the entire table, go to Edit menu>Search. Typing one or several initial letters within one column will scroll to the first matching value.

You can right-click the desired Results list column head and select to sort it alphabetically. Clicking an item to scroll the column into the visible range of the list.

On the data area, a list of functions is faded in for object processing. Available functions are:

Edit Starts the Results List Inline Editor. (!!!Make this a hyperlink: 3.1.5 The Results List Inline Editor!!!)

Copy This function copies the selected values to the clipboard. Rows will be separated with a linefeed and a carriage return character; columns will be separated with tabs.

Copy with Header This function copies the selected values to the clipboard, including the header names of the selected columns in the first line. Rows will be separated with a linefeed and a carriage return character; columns will be separated with tabs.

Duplicate Duplicate copies all selected values in a separate data grid.

Add to compare list The selected objects are added to the Object Compare list.

Sort Sorts the result data ascending or descending by the selected column.

Goto... Enables the fast change to a line or a column for the Results list. Entering a number enables vertical scroll, entering a column header or selecting one from the will enables horizontal scroll.

Marks Used to select different objects in the Results list. You can toggle or scroll marks to the next or previous marked object. Marks are mainly used by the Compare Data function, but can also be set manually.

Object functions Thisis where user-defined functions for objects in the Results list are provided, such as Change ACL, Dump Object, Last SQL statement, Request PDF rendition and so on. You can manage object functions in the Options Dialog. Object functions are available depending on the selected type of document and the individual configuration.

Export to Exports the selected cells of the Results list to CSV or Microsoft Excel (you need to have Excel installed to be able to export to this format). If the amount of exported data exceeds the Excel limitations of 65535 lines and 256 columns, more than one Excel tab sheet will be used. You cannot export data to Excel if a remote Office 365 installation is used; if this is the case, use the Copy with Header command.

Generate Script Opens the Script Generator that lets you generate DQL or API scripts from the selected data. Additional type dependent script templates will also be available, if the appropriate object type is selected.

Plugin Functions If dqMan Plugins that supply object related functions are installed, these functions will be displayed at the end of the context menu.

The Results List Inline Editor

You can edit values directly in the Results list, if the results contain the r_object_id attribute. Press Enter to save any changes. Pressing Esc or moving the focus to any other control will close the editor without saving.

Single Attributes For single attributes, a standard input field will be created in the corresponding cell of the grid. Some attributes display a list with possible values. This list is filled in either with the values of a data dictionary value assistance or with manually configured values from the file dqManValuelists.xml.

Repeating Attributes You can modify Repeating Attributes within a small sub grid. As DQL results do not show the correct order of repeating attribute values, the contents of this list can differ from the displayed values in the Results list. The sub grid offers an own context menu for inserting, deleting or reordering values of the repeating attribute.

Multiple Single Attributes If the Results list contains more than one result, you can edit a single attribute of multiple objects simultaneously. Select more than one value in a column and start the editor. The values you enter are applied to all the selected objects.

Linked Repeating Attributes You can modify linked repeating attributes of one object such as r_accessor_name, r_accessor_permit and r_accessor_xpermit of dm_acl in a multicolumn sub grid. Select more than one column of repeating attributes and start the editor.

Multiple standalone or linked repeating attributes You can also modify standalone or linked repeating attributes of more than one object at the same time, if the selection is extended to more than one object (line) in the result grid. The values you enter are applied to all the selected objects.0

The Attribute Filter

You can filter query results by the queried values using the attribute filter, which can be open for each column. You can combine filters and use them for multiple columns using an “and” operation.

To open an attribute filter for a column, click the button in the column header and then, in the filter dialog box, you can see the filter options depending on the column data type.

Click Apply Filter to activate the filter after selecting the filter options. If a filter is active, the filter button in the column header and the row numbers are highlighted.

Additionally, all filter buttons in column headers have a context menu.

If at least one filter is active, the top left cell of the result grid also displays a filter button with an active context menu with one additional function: “Generate Predicate”. Executing this function generates a predicate (part of a "where" clause) from the current filter settings and copies it into the clipboard, enabling you to add it to the current query to replace the filter settings. Example:

(Upper(object_name) like 'DM%') and (globally_managed in (0)) and (acl_class < 3)

The Message Area

The Message Area logs the executed DQL commands and their results. The context menu offers some settings to influence the behavior:

Settings:

You can activate the Message Area from the View menu.

The Describe command

You can enter the Describe command in the DQL input window and it displays all attributes and selected characteristics for an object type.

Syntax:

Describe <type> [all|custom] [with name='<name>'][,locale=’<locale>{,<locale>}|all’] Describe <table> [name='<identifier>']

Arguments:

You can modify attribute labels directly in the Results list, using the edit function from the context menu. Changed labels are published immediately. To delete labels, simply enter an empty value; in this case, the inherited label from the supertype is displayed.

Examples:

The Describe command is also available from the context menu of the input area. The function is activated if the context menu is open on the name of an object type or a registered table. This call corresponds to the Describe <type or table> all command.

Describe options: The Describe options enable you to customize the columns and their order of the describe Results list. Available columns are predefined and you can select them by selecting the respective checkbox. Moving columns upwards or downwards alters the default order.

The column “owner” is only displayed if the argument all or custom is used and attributes from different type levels in the hierarchy are displayed. In this case, also the type owned attributes can be marked by selecting the Mark owned attribute labels checkbox. This functions gives a good overview whether a type uses the inherited label or overwrites it with own values.

DQL Favorites

You can save any DQL queries to the Favorites view for easy, quick access.

You can open Favorites from the Edit menu. To store a query, go to Edit menu>Save to Favorites, in which case either the whole content of the input area or only your selected content (if any) will be saved as favorite. When saving a query to Favorites, enter the following details:

Name Name of the query.

Category Select a category for your query, such as Workflow, ACL, Users and groups. Your favorited query will be grouped under the mandatory category you select at this point.

Query type Select the desired query type from the list, for example Select, Update, Execute etc.

Object type Select the desired object type from the list.

Show in Favorites (If Applicable) Select if you want your query to be displayed in the Favorites section.

Show in Repositories Click the Login history button and decide whether or not this future favorite will be displayed in the current repository or not.

Description Enter a meaningful description of the query.

DQL Query Displays the DQL query that you want to add to Favorites.

Favorite Menu To add a query to the Favorite menu, select the Add to Favorites Menu checkbox.

Docbase List enables the allocation of queries to one or more repositories. An exclamation mark placed in front of the repository name, e.g. „!testdocbase“, hides this query if this repository is active.

Repositories are stored by their repository ID. If you are working with clustered content servers or use fully qualified repository names, every repository needs to be listed only once.

To load a query from the favorites, click Edit menu>Load from Favorites.

A search filter is located at the top of the window, enabling you to freely combine your search criteria. Searchtext does a full_text search in all available favorite attributes. All queries that match the filter criteria are displayed in the center of the window. Double-click the query to copy it to the DQL View input area. If a description exists for a query, it will be displayed in the lower part of the window if the query is selected.

Additionally, you can manage your favorites in this dialog box by clicking the Manage button and display the additional button list:

Click Import to import existing favorites from your file system.

Click Export to export all selected queries to the file system.

Click Edit to modify the selected query.

Click Delete Query to remove all selected queries.

Click Save to preserve your changes.

The Favorite menu

You can add your most frequently used DQL queries to the Favorite menu by selecting the Add to Favorites checkbox in the Store to Favorites function.

All queries in this menu are grouped by the entered categories that in each case represent a submenu. From there the appropriate queries can be selected by their names. Selected queries are copied to the DQL command input area.

Pressing <Ctrl> when selecting a query will insert the query at the current cursor position. (Note however that template field options will not be merged automatically). Otherwise, the DQL command input area will be cleared before inserting the query.

Template Queries

Template Queries are DQL queries that contain placeholders for values. When executing a Template Query, you need to enter values for the placeholders.

Placeholders consist of a freely selectable name, enclosed by { } characters. You can insert placeholders either manually or with a function available in the context menu of the input window. Template Queries can contain any number of placeholders.

If placeholders appear in a query more than once, they always represent the same value.

You can improve the behavior of placeholders by adding placeholder options, using the Edit template field option from the context menu.

Various types of value lists are available in Value List Type, as follows:

If the result of a DQL query contains more than one attribute, the value of the first column will be displayed in the value list and the corresponding value of the second column will be inserted in the query.

In a fixed value list, you can make a distinction between the displayed value and the inserted value using the || separators (for example, Label||Value).

The query Select object_name, r_object_id from dm_documentwill fill the list with the object_name attribute of all dm_document objects. Selecting a name from the list returns the r_object_id for the placeholder value.

Using Check Syntax, you can verify the syntax of the current DQL query. This feature is only available, if a valid session exists.

Formating DQL Queries

You can format DQL queries automatically. The associated format templates are defined in the file dqManFormatTemplates.xml.

To format a query, click on the query in the DQL input area and select the function Auto Format Query from the context menu of the DQL input area.

The Query:

Select r_object_id, object_name, acl_name from dm_document where object_name like 'dm_%' or object_name like 'xy_%' order by r_object_name, acl_name

Will be formatted to:

SELECT r_object_id,

object_name,

acl_name

FROM

dm_document

WHERE

object_name like 'dm_%' or

object_name like 'xy_%'

ORDER BY

object_name, acl_name

To clear the formatting of a query (unformat), use the Unformat Query function from the context menu. Calling this function removes all tabs, multiple spaces, line feeds and carriage returns from the query, leaving a plain single line query.

The third formatting function Extract Query can be used to extract the DQL part out of a piece of program code. From this code:

String query = "Select * from pl_produkt (all) where i_chronicle_id = '" + chronicle_id + "' and " + "valid_from <= Date (Today) and " + "Dateadd(day,1,valid_to) > Date(Today) and " + "any r_version_label = '_NEW_'";

This query will be extracted:

Select * from pl_produkt (all) where i_chronicle_id = '' and valid_from <= Date (Today) and Dateadd(day,1,valid_to) > Date(Today) and any r_version_label = '_NEW_';

Note that the variable chronicle_id is removed, leaving an empty value to be filled …where i_chronicle_id = '' and…

Repeated Queries

DQL queries can be executed repeatedly and automatically in a selectable or freely definable interval, causing the results to be refreshed accordingly.

The function is available in the context menu of the DQL editor. (Repeat Query every…). After selecting the interval, a yellow notification bar is displayed at the top of the DQL editor counting down to the next query execution. Automatic execution can be stopped at any time by selecting Stop Repeat Query from the context menu or from the notification bar.

In case of automatic execution the message area will not be deleted and will display the full log containing all the executions.

The History records all successfully executed DQL and API commands for further use. You can control it using the toolbar.

Clicking Back or Next loads the corresponding query into the input control, replacing the existing content. The History list displays all recorded commands.

To copy a command, either double-click it or use drag-and-drop. The content of the target input area will be replaced, unless a part of it has been selected.

Copying a command to a script view will insert the command at the current cursor position without overwriting the existing content, unless something is selected.

The history is displayed on the left side of the session window by default, but it can be moved around and anchored in different places of the session window.

You can add a predefined or customizable filter in the Dropdown control in the header of the history list. In the example, dm_format is a manual filter, resulting in a list of all queries containing dm_format.

In dqMan, you can view and modify some type definitions, which are available from the context menu of the DQL result list after executing a describe command, or from the folder tree in the repository navigator.

All changes can be applied directly or you can generate a script for later or multiple use.

dqMan enables you to view, edit and copy attribute definitions. These are available from the context menu of the DQL result list after executing a describe command.

The attribute properties always apply to the described type, not to the type from which the attribute is inherited.

Dump Attribute

A dump of an attribute lists all definitions from the data dictionary similar to an object dump.

Edit Attribute

In the attribute editor, you can modify frequently used attribute definitions, such as general settings, search options, labels, user interface hints, value assistance and value mapping. The editor enables you to work with all the locales without switching the session locale. All changes are either directly applicable or you can generate a script for later or multiple use.

• Modify attribute settings

• Add, remove or reorder value lists

• Manage value mapping, even copy & paste entire lists, and with all the locales in one dialog

• Modify value assistance content, order fixed lists or execute DQL queries to control results.

Copy Attribute

This function creates a script from existing attributes which can be used to copy attributes between different object types or between repositories.

Select target type, locales to copy, attribute property areas and publishing options.

Rename attributes and change repeating flag if necessary.

Review generated script. Click Back to change settings, Save script to save the script to the file system or choose a session to directly execute the generated script.

The Repository Navigator is available in the DQL view, to the left of the dqMan screen. You can open or close it using the Repository Navigator from the View menu or by using the Navigator button on the toolbar.

The Repository Navigator displays a cabinet/folder tree, an object type/registered table tree, a group tree and a favorites tree for the currently connected repository of the session window.

Whenever a tree item is expanded, the appropriate data is fetched dynamically from the repository. Therefore, you can easily update a part of the tree by collapsing and re-expanding the parent folder.

The Cabinet/Folder Tree

Create a DQL query for the folder contents Click the desired folder to create a DQL query for the folder contents, placed in the DQL command input area without executing it. The query is created using the Default Query Template that you can modify in the Options dialog box.

View the folder content Center mouse click to create a DQL similar to the above, but automatically executed.

Context menu Right-click a folder to open the context menu:

Object functions and plugin functions are also available, if they have been enabled for the Repository navigator.

The Object Type/Registered Table Tree

Create a DQL query for type objects or registered tables Click an object type/table to create a DQL query for objects of the selected type/rows of the selected registered table using the Default Query Template. The result is displayed in the DQL command input area without executing it. To execute it, use the center mouse button.

Context menu Right-click an object type/table to open the context menu with the following options:

The Group Tree

Creation of a DQL query for group objects Click a group to create a DQL query for the group using the Default Query Template. The result is displayed in the DQL command input area without executing it. To execute it, use the center mouse button.

Context menu Right-click a group to open the context menu with the following options:

The Favorites Tree

Load a favorite query Click a favorite to load the DQL query of the favorite into the DQL command input area without executing it. To execute it, use the center mouse button.

Context menu Right-click a favorite to open the context menu with the following options:

The Object Navigator, located by default to the right of the dqMan screen, provides easy, fast and comprehensive access to the properties and connections (such as ACLs, owner names, relations, subscriptions, lifecycles, workflows and so on) to any other object in the repository.

You can edit any properties directly in the Object Navigator and you can also follow connections to other objects similar to a web browser by simply clicking the link to open the dependent object in the Object Navigator. Moreover, all available actions like object functions, type scripts and plugins are also available making Object Navigator first choice of working with single objects.

You can open Object Navigator and load new objects in any of the following ways:

• Use any explicitly identifiable object anywhere within dqMan, such as r_object_ids in any text area such as lists, logs, tails and so on, or Any object in the Repository Navigator, or Distinct values in the DQL result list, such as acl_name, owner_name, r_object_type and so on. After selecting an identifier, you can load the object into Object Navigator either by pressing F12, by selecting Extras menu>Navigate Object or by long-clicking the object and then releasing the click when the cursor changes.

• If the clipboard contains a valid r_object_id, you can load this object by pressing Alt+N or by clicking Extras menu>Navigate Object from Clipboard.

• Follow a link to a dependent object, as described earlier in this publication.

• Press Alt+O or click View menu>Object Navigator to open it without selecting any object. This is useful to display an already loaded object again or to use the Quick Pick function (see later) to directly search for an object.

• Load an object within an object function using the script command FetchObject.

After any of these procedures, the Object Navigator will open if it is not already visible.

For handling objects, the Navigation Bar has functions that you can identify by the tooltips displayed after hovering your cursor above the desired icons:

The Quick Pick search function provides fast access to objects in the repository. You need to enter two strings in the top edit field to start a search:

• The first string is part of the object type to be searched in. You can either enter the complete type name, such as dm_user, or part of the type name, such as user. In the latter case, the search will be conducted in all types containing the keyword user in the type name (dm_user, dm_message_user_data, dm_message_route_user_data, dmc_workqueue_user_profile and dmc_wq_user_skill).

• The second string is a part of the object name. Valid searches include, for example, user admin, acl preset, folder template and so on.

Press return or click Search to start the search. Search results are displayed in a list and you can double-click or press Enter to open the selected object in the Object Navigator. Single objects are loaded without showing the result list.

The result list remains available until the next search.

If only one search string is provided, the search is presumed to be run in the default dm_sysobject type. In the title bar, the name of the currently selected object and its type are displayed.

The attribute area displays all the attributes of the object and their values, which you can modify within the navigator. The context menu of the attribute area provides additional functionalities, as follows:

The tabs at the top of the attribute area provide various ways to order the attributes.

The connection area contains more links to other objects, depending on the object type. If this connection is using another object, such as a dm_relation object, the link to this object is also provided in the Via column.

Predefined connections include, among others:

• Relations

• Subscriptions

• Ownerships

• Memberships

• Virtual parents or children

• Lifecycles

• Workflows

• Folder links

The listed connections are usually limited to 50 for performance reasons. If all are needed, the context menu offers a function to execute the underlying query in the DQL window.

Configuration

The Object Navigator configuration is stored in the file dqManObjectNavigator.xml in the /config subdirectory of the dqMan home directory (c:\program files\dqMan).

The configuration is done in different sections within the file, as follows:

• Section <identifiers>

Identifiers are used to uniquely identify objects by the value of an attribute (for example, an acl_name identifies a dm_acl object) and are used in the DQL result list or the Object Navigator itself.

The attributes can be either single or repeating. Identifiers consist of an attribute name (columnname="acl_name") and a qualification (qualification="dm_acl where object_name='{*}'”). The value of the attribute is represented by {*}.

<identifier columnname="acl_name" qualification="dm_acl where object_name='{*}'" />

<identifier columnname="a_content_type" qualification="dm_format where name='{*}'" />

<identifier columnname="content_type" qualification="dm_format where name='{*}'" />

<identifier columnname="r_accessor_name" qualification="dm_group where group_name='{*}' union select r_object_id from dm_user where user_name='{*}' and r_is_group=0" />

• Section <copy_attributes>

Copy attributes fill the submenu of the Copy Value of function from the Attributes area. It is a simple list of all possible values. The submenu is filled with all attribute names that are valid for the currently loaded object.

<copy_attributes> <attribute name="r_object_id" /> <attribute name="object_name" /> <attribute name="group_name" /> <attribute name="user_name" /> </copy_attributes>

• Section <translations>

Translations are used to make cryptic attribute values more readable. (e.g. Boolean values can be translated to true or false). To take effect, translations have to be assigned to attribute values in the objecttypes section.

<translation name="user:user_state" bitwise="F"> <value source="0">Active</value> <value source="1">Inactive</value> </translation>

<translation name="boolean" bitwise="F"> <value source="T">True</value> <value source="F">False</value> </translation>

• Section <objecttypes>

The objecttype section assigns translations to the attributes of an object type and defines queries for connections to other objects. Object types can inherit definitions from other object types.

The type dm_cabinet inherits all settings (translations and connections) from dm_folder. Additionally, the attribute is_private is assigned the translation named boolean:

<objecttype name="dm_cabinet" extends="dm_folder"> <attributes> <attribute name="is_private" translation="boolean" /> </attributes> </objecttype>

Connections are defined as a DQL query, whereas defined labels are used to assign the result to the Object Navigator columns.

<relation name="packages" label="Workflow Packages" limit_to="50"> select r_object_id as relation_id, 'dmi_package' as relation_label, r_component_id as target_id, r_component_name as target_label from dmi_package where r_workflow_id = '{r_object_id}' order by 4 </relation>

The number of results of a query can be limited by setting the limit_to value for the connection. This is useful to limit the loading time of an object.

Attributes in curved brackets reference the currently loaded object in the navigator.

The resulting values are displayed in the Object Navigator: target_label in the column To/From and relation_label in via. If the label is omitted, the target_id or relation_id will be displayed instead. If no relation value is queried, the column via remains empty.

This chapter describes only the basic principle of the Object Navigator configuration. There are many more examples to be found in the dqManObjectNavigator.xml.

In dqMan, there are two functions to view external text files like log files or trace files, or anything else like notes, code snippets, readme files and so on.

To open any text file, go to View>View File; to open a new file, click Open.

As files open, a submenu with the most recently opened files is also added to the View>View File menu allowing these files to be quickly opened again if needed.

The File View

The File View displays the contents of the file. Use the context menu to access additional functions such as refresh, search, dump object or word wrap settings.

With this tool, you can generate DQL, API, Docbasic or other scripts from a data list, either a DQL query result list or an external data list. The tool is available from the context menu of the list calling the function Generate Script.

Script Templates

A script template represents the basis for a script. It consists of three areas: header, body and footer. The header and the footer can only contain static text, added exactly once at the beginning and/or at the end of the script.

The script body is applied to each line of the data list. The script thereby contains one copy of the script body for each data record. The script body can contain text, placeholders for data from the data list and processing instructions.

With the generation of the script, the placeholders are replaced by data from the data list. The processing instructions are removed.

Placeholders

In the source data list, you need a placeholder consisting of a column name enclosed by curved clips, for example: {r_object_id} or {object_name}.

If the data list is a DQL query result list, placeholders can contain any attribute of the underlying object type. If this is available in the data list, the value is taken from there. If not, the value is loaded from the repository object.

To insert placeholders, click Insert Querycolumn from the context menu, then select one of the available placeholders that are part of the data list from the submenu.

Entering a left curved clip in the editor area or pressing strg+Space will open a selected list containing all the attributes of the referenced object type.

Placeholders with no reference to the data list will be displayed in cursive (italic).

Processing instructions

There are two processing instructions available: LOOP and IF EMPTY.

The LOOP Instruction

LOOP enables the processing of values of repeating attributes, for example:

{LOOP r_version_label} ...{r_version_label}... {END LOOP}

You must specify a repeating attribute in the LOOP instruction to resolve the attribute to single values. To process more than one repeating attribute simultaneously, you can specify all attributes using commas as separators:

{LOOP r_accessor_name, r_accessor_permit, r_accessor_xpermit}

This is called a combined loop. The recurrence frequency of a loop is determined by the amount of values in the first repeating attribute. You can create loops from the context menu.

The IF EMPTY Instruction

This instruction enables the processing of empty attributes. Example:

{IF EMPTY(title)} ... set,c,{r_object_id},title ... {ELSE} .... {END IF}

The attribute must be defined in brackets. Within a loop, repeating attributes can be processed.

IF EMPTY instructions must not be nested.

Examples

Example 1: Concatenate attribute values into a separate attribute.

This example will produce an API script that concatenates the values of object_name and title in the attribute subject, separated by a hyphen.

set,c,{r_object_id},subject {object_name}-{title} save,c,{r_object_id}

Example 2: Loop a repeating attribute.

This example turns all values of authors to capital letters. The basic DQL query (select *, Upper(authors) as uauthors from dm_document) supplies the values in capital letters in the repeating attribute uauthors.

truncate,c,{r_object_id},authors

{LOOP uauthors} append,c,{r_object_id},authors {uauthors} {END LOOP}

save,c,{r_object_id}

Manage Script Templates

You can save script templates for further use by clicking the Save button; you can open scripts by clicking the Load button on the toolbar and then selecting one from the Open File dialog box.

Click the downward arrow to open a submenu that contains all the templates saved in the subdirectory .\Scripttemplates inside the dqMan program directory.

The History Section

Recently created script templates are automatically stored in History. Click the Back and Next buttons to load templates from History.

Script Types and Options

Selecting the script type enables dqMan to enhance the script generation process.

Add Data Sources

You can generate a script from two data sources simultaneously, the additional source being another DQL query result or a data list. You can open the additional data source by clicking the Add Source button of the toolbar and then selecting from the possible data lists on the submenu.

The additional data source must be joined with the main data source to enable correlation of the data records. At least one column of the main data source must be joined with one column of the additional data source.

To join to columns, select the columns in both lists and click the Join button. You can also use drag-and-drop onto the opposite list. To delete a join, use the context menu of the Selected Columns grid.

After a successful join, you can add placeholders to the script template from the context menu or value lists. The placeholders have the following format:

{data:object_name}

Generate a Script

You can generate a script from the template by clicking the Generate button. During script generation, the Stop button is activated so that you can halt the generation process and return to the script template.

If the script is finished, the label changes to Template. Click it to go back to the script template.

You can save or execute a generated script.

Execute a Script

Click Execute Script to copy the script into the appropriate script view of the active dqMan session window or, depending on the script type, to open the Docbasic interpreter.

If the script should be executed in a different session, the available sessions are displayed in a submenu that you can open by clicking the downward arrow button.

You can also open a new session from this menu. The script generator closes automatically.

Type Dependent Script Templates

Type dependent script templates are a special variant as they are bound to a certain Documentum object type, identified by the type tag. This type of script template will be available directly in the DQL result list context menu, if the list contains a column with r_object_id values. Additionally, these script templates do not depend on the values of the result list. Only the r_object_id is mandatory. All other attribute values are loaded from Documentum during the generation process.

You can generate type dependent script templates using the script generator and you must save them in the subdirectory .\Scripttemplates within the dqMan program directory. Furthermore, while saving the script, you need to save the type Typescript in the Save File dialog box. In addition, you need to name the template and select a type tag in an additional dialog box.

Additional data sources are not allowed in type dependent script templates.

An example is available to you in dqMan: ACL Create Script:

Script Header:

# ACL Create Script Template # Created 06/26/2004 # --------------------------------------------------------------

Script Body:

# Create ACL {object_name} create,c,dm_acl set,c,l,object_name {object_name} set,c,l,description {description} set,c,l,owner_name dm_dbo set,c,l,acl_class {acl_class} {LOOP r_accessor_name,_accessor_name,_accessor_permit,_accessor_xpermit_names} grant,c,l,{_accessor_name},{_accessor_permit},{_accessor_xpermit_names} {END LOOP}

save,c,l # -------------------------------------------------------------

Script Footer: # END ACL Create Script

Note the use of the computed attributes _accessor_name, _accessor_permit and _accessor_xpermit_names in the LOOP instruction. Since computed repeating attributes are computed on demand, they usually return the wrong number of contained values.

To ensure the correct processing of the LOOP instruction, the regular attribute r_accessor_name of the type dm_acl is included in the loop attribute list at the first position, without being referenced within the loop.

Script Assistants enable you to develop complex API or DQL scripts.

Dump & Load

Click Extras menu>Dump & Load <repository name> and then select select the available dump types from a submenu. The result script is copied into the API Script View of the active session window.

Dump entire docbase

1. On the first page of the assistant, manually enter the full path to the dump file (since the path references the local directories on a remote server).

2. On the second page, determine the options. For more information about Dump options, see the Documentum Content Server Administrator’s Guide.

3. On the last page, you can see the generated script, which you can modify, if necessary. Click the Finish button to copy the script into the API script view of the active session window for execution.

Dump Specified Objects

In order to only dump specific objects, use the Dump specified objects function, as follows:

1. On the first page of the assistant, manually enter the full path to the dump (since this path references the local directories on a remote server).

2. On the second page, select the desired object types. To specify certain objects of the selected type, you can add a Where Clause. The keyword Where is generated automatically if a clause is not empty.

3. On the third page, you can determine the options. For more information about Dump options, see the Documentum Content Server Administrator’s Guide.

4. On the last page, you can see the generated script, which you can modify, if necessary. Click the Finish button to copy the script into the API script view of the active session window for execution.

Load Docbase

1. On the first page of the assistant, manually enter the full path to the dump (since this path references the local directories on a remote server).

2. On the second hird page, you can determine the options. For more information about Dump options, see the Documentum Content Server Administrator’s Guide.

3. On the last page, you can see the generated script, which you can modify, if necessary. Click the Finish button to copy the script into the API script view of the active session window for execution.

Copy registered Table

The Copy registered Table assistant enables you to copy registered tables completely. The result script can create a database table, register it and copy the content. You can execute each part independently from one another, so you can also copy data between two existing tables only.

This assistant is available either in the Extras menu, but only if called from a session window with an active session, or also in the Repository Navigator’s Types/Tables tab, if a registered table is selected.

You can save or copy the generated script into the DQL view of an either existing or new session window for execution.

Select registered tables and operations

On the first page, select the registered table and at least one operation. The operations available to you at this stage are:

Select the Hide system tables checkbox to remove all system tables from the list.

Select the target database type and columns

This page is available if you have selected the Create table creation script operation.

You must select the target database type in order to generate the correct SQL commands for table creation.

On this page, you can give your created table a new valid name by filling in the Target table name.

Furthermore, you can exclude single columns from the source table. Cleared (unselected) columns are copied, registered or filled with data. You must select at least one column.

Registration and permissions

This page is available if you have selected the Register table in target system operation.

The option Register all columns does a complete registration of all copied columns with names and types. This option is only active for selection if the table is not fully registered in the source repository. If selected, registration will differ between source and target repositories.

The table permissions are initialized with the permissions of the source table, but can be changed if necessary.

Data selection If you selected the Copy content operation, you can add a where clause for data selection.

Result The last page displays the generated script. Click the Save script button or copy it into the DQL script view of an existing or a new session window for execution using the Execute in... button.

The assistant closes down automatically if the script is copied into a session window.

Change Objecttype

You can use Change Objecttype assistant to modify the object type of objects. To open the Change Objecttype assistant, go to the Extras menu, but it is only available if called from a session window with an active session and the DQL command view selected. Furthermore, a DQL query result must be available that includes the r_object_id attribute.

All selected objects in the result list must be of the same object type. Supported types are dm_document, dm_folder and dm_cabinet with their descendants.

You can save the generated script or you can paste it into the DQL view of the current session window for execution. To use the Change Objecttype assistant:

1. Select a new type for the objects from the available types in the current repository. When selecting a new type from the type tree, the required migration path is displayed at the bottom of the window and the Next button is activated.

2. Map all attributes from the old type (that will be lost through the change in type) to attributes of the new type. These attributes are displayed in the left column of the attribute mapping window. Selecting an attribute of the new type from the menus available on the right will create the mapping between the old and the new attribute. All attributes including their values that are not mapped will be lost. The lists display only attributes of the new type and which share the same data type as the old attribute. Additionally, you can map repeating attributes of the old type to repeating attributes of the new type only; single attributes can be mapped to single attributes only.

To change this behavior, change the options:

• Deactivate Show type related attributes of target object types only to select from all attributes of the new type.

• Deactivate Show matching data type only to map different data types.

The generated script is displayed on the last page. You can Save script or you can copy it into the DQL script view of the current session window for execution clicking Finish.

On the third page you can activate some optional features:

There are two ways to compare data:

• The Compare data function from the Extras menu enables you to compare different data lists, for example DQL query results with other DQL query results or with imported data lists.

• The Object Compare List enables you to add single objects of any type, from any repository. These objects are compared attribute by attribute and you can modify them directly in the list.

The „Compare Data“ Function

This function is only available if at least two different data lists are open. These can be results from DQL queries from any repository or imported data lists. The assistant is described in the following sections:

Settings

First, select the two different data lists to compare from the dropdown menus. Subsequently, the comparison function is determined. The following functions are available:

You can customize the comparison using the options Compare case sensitive (which compares case sensitive occurrences) and Compare exact order of repeating attributes (repeating attributes can have the same values, but in different order).

Data Columns

The two data lists must allow correlation of the data records. At least one column of the source data list must be joined to one column of the target data list. These operations are performed in the second page of the assistant.

To join to columns, select the columns in both lists and click the button Join or drag-and-drop the desired columns onto the opposite list. To delete a join, use the context menu of the Selected Columns grid.

Selecting Search for different records causes the comparable columns to be defined additionally, which you can do using the Compare button or by pressing the Ctrl during the drag-and-drop of one column onto the opposite list.

The search is then performed for objects that can be joined by all Joins to columns, but that differ in the Compare to columns.

Results

The results of the comparison are displayed on the last page.

The number of found data records can differ for both lists, since the criteria can be fulfilled by more than one data record.

Work with Marked Records

The result of the compare operation are displayed in the corresponding data lists. All found records are marked as such. If the function Search for different records was executed, the rows with differences are highlighted.

The marks remain until either a new DQL query is executed in the session window, a new data compare is run or the marks are removed manually using the respective function from the context menu.

You can process marked records as a group, similarly as selected data records. Object functions, export functions and the Script Generator support marked records.

To execute a function for all marked records, you must select exactly ONE cell of any marked record and start the function. Selecting more than one cell or an unmarked cell causes the function to be be executed for the selected objects/cells only.

If the compare is executed using the Search for identical records or Search for different records functions, the rows in the two grids are linked to each other. Use center mouse click on a marked record in one list to scroll the other list to the corresponding record.

If more than one record from one list is linked to a single record in the other list, repeated mouse clicks on the single record will loop through all linked records successively.

If a Search for different records is executed, the function Add to Compare List will add the selected object and all the corresponding objects to the Object Compare List in one go if only one object is selected. The Object Compare List will be cleared first.

The Object Compare List

In the Object Compare List you can add single objects of any type, from any repository, for example a dm_acl object from repository A could be compared with a dm_cabinet object from repository B.

Tp add objects from the DQL query result list, call the Add to Compare List function from the context menu. There can be only one Object Compare list. All objects will be added to the same list which is automatically created when the first object is added. Closing the list removes all objects.

The attributes are aligned vertically. The object in the first column is the master object. All other objects are compared to the master object and differences are highlighted. Differences in single values of repeating attributes are displayed in red font color.

To change the master object, drag the new master object to the first column. If different object types are compared, attributes that are invalid for the object type remain grey and empty.

You can refresh the values of a column and also delete a column.

The context menu of the list offers additional functionalities, as follows:

Normally, you can only add one instance of an object to the list. If an object is sent to the list a second time, the list entry is updated without adding the object a second time.

Sometimes it is useful to follow the changes of an object throughout its process. Therefore, you can freeze an object by clicking the button in the header of the object.

Additionally, the i_vstamp value is displayed in the header.

The DQL Script and API Script views are described together since they provide similar functionality for executing scripts. A script is a sequence of multiple DQL statements or API commands that will executed in succession.

It is not possible to mix DQL and API in the same script, hence the separate views for executing one or the other type of script.

The upper input area is where you enter the script and the script results are logged in the lower section.

Double-clicking an element in the script log copies the value to the clipboard. Press Ctrl when double-clicking to paste the value into the active input control at the current cursor position.

The actual script can be typed/edited directly in the upper code editor area of the window, pasted from the clipboard, loaded from an external file or generated in dqMan using the built-in Script Generator:

• Load from file: Either use the Load Script function from the Edit menu, or the Navigator (folder tree) or drag-and-drop the file to the input area.

API scripts typically consist of a sequence of individual API commands, one per line. API command that need an input value will have the command on the first line and the value on the following line.

DQL statements can consist of more than one line. Therefore DQL statements in scripts must be terminated by a semicolon ";"

Each line beginning with the the# or with the // is regarded as a comment line. Comments will be ignored during execution and have no effect on the result of the script.

Execute Scripts

You can execute scripts either end-to-end or step by step. You can control the execution using the toolbar or the context menu.

Additional functions are available in the context menu.

Run to Cursor executes all commands from the current cursor position or from the beginning to the selected line. The command in the current line is highlighted and debug mode is turned on.

In debug mode, you can select to execute the next command using Set Next Statement. This can be used to place the next statement/command that will be executed anywhere in the code, thus skipping errors or unneeded steps.

Breakpoints can also be set to control the execution of a script. Any number of breakpoints can be set anywhere in a script using the Set/Remove Breakpoint context menu items respectively. Breakpoints will be set/removed on the line where the context menu is opened, and will be marked with a red dot to the left of the line as well as highlight. It is also possible to remove all breakpoints at once when they are no longer needed using the Clear All Breakpoints content menu item.

The Script Navigator

The Script Navigator is a directory tree for all available local drives, enabling fast access to stored API and DQL Scripts.

The Script Navigator is available in the API Script view and the DQL Script view, to the left of dqMan screen.

You can open a selected script using the Return key or by double-clicking it. Open scripts are marked as such until the session window is closed. Additionally, you can toggle the marks using the function Mark as New and/or Mark as Opened from the context menu.

Default settings for file extensions are .api, .apiscript, .dql and .dqlscript. You can filter them using the function Filter from the context menu.

Error Handling

The option Stop on Errors in the script editor's context menu defines the error handling behavior:

• When this option is active, the script pauses in case of error and highlights the faulty statement/command. The statement or command affected by the current error will be highlighted in its entirety (even if it spans multiple lines) to clearly show which part of the script is affected.

• If this option is inactive, the script will not stop execution but will display error messages in the result log.

• Error handling will always pause on any error, prompting you to take action before resuming execution (for example, to fix the error or place the cursor after the error to skip it).

In an API script, you can turn on/off error handling using the script command #$ StopOnErrors on|off.

Using Variables in API Scripts

You can use temporary variables in API scripts to store return values for further use. The values of the variables remain during a script run until either the execution of the script is terminated or the content of a variable is overwritten.

Variables in API scripts are not compatible to the Documentum API language. Scripts with variables cannot be executed by other applications. However, the command line program dqAPI and Pack&Go Scripts support variables.

Naming conventions The name of a variable can be chosen freely but it needs to be enclosed within percentage signs. They are not case sensitive. For example:

%1% %File-Contents% %this is a variable%

Assignments You can assign constants or results of API commands to a variable. For example, %Repository_Owner% = dmadmin initializes the variable %Repository_Owner% with the value "dmadmin" (you can also use the Define command from earlier dqMan versions, but it is marked as deprecated). Also, %ID% = id,c,dm_document where object_name like 'a%' assigns the result of the API command to the variable %ID%.

Concatenating values You can concatenate values in two ways:

• %ID% =+ Add this text

• %ID% = %ID% Add this text

Usage To use a variable, insert it at the appropriate position in the API command: get,c,%ID%,object_name.

Query variable contents When executing the script in debug mode, you can query the values of the variables. Click the variable and wait for the hint to appear.

Using Script Commands in API Scripts

Script commands are additional commands that expand the functionality of API scripts or object functions. Using script commands in API scripts is not compatible with the Documentum API language. Scripts with script commands cannot be executed by other applications, except dqAPI and Pack&Go Scripts.

Available script commands are:

Example of a collection loop:

%Collection%=readquery,c,select group_name from dm_group where any i_all_users_names = 'dmadmin'

#$Loop %Collection% %group_name% = get,c,%Collection%,group_name #$ Print Group name %LoopIndex1%: %group_name% #$EndLoop

Use the #$EndLoop command to handle the collection. You do not need to add next or close commands.

The %LoopIndex<i>% variable only exists within a loop and contains the current loop index, starting with 0. %Loopindex1% is the index of the first loop. %Loopindex2% should be the index of the second loop, if it is nested within the first loop.

Example of an attribute loop:

%id%= id,c,dm_document

#$Loop i_folder_id(%id%) %Folder_ID% =get,c,%id%,i_folder_id[%LoopIndex1%] #$Loop r_folder_path(%Folder_ID%) %FolderPath%=get,c,%Folder_ID%,r_folder_path[%LoopIndex2%] #$ Print %FolderPath% #$EndLoop #$EndLoop

The %LoopIndex<i>% variable is incremented every time the #$EndLoop command is executed. It can be used as an index for the repeating attribute values.

Logging

During the execution of scripts, the result of the commands are logged in the result log. You can define logging behavior in the Settings of the result log context menu.

The following logging settings are available:

You can import data (not documents) from external sources into a repository using the import function. A data import takes place in two stages. First the data is loaded into a dqMan data grid, then the data is processed using the script generator.

The Import function is available in the Extras menu. In the File Open dialog box, you can select Excel files, CSV or text files.

Depending on the selected file type, you will be helped by the import assistants, as you can see later in this document.

Import CSV or Text Files

Import from Clipboard

You can also import data directly from the clipboard, if the data is of type text. Calling this function opens the CSV import assistant.

Using Jobs, you can establish a session to any available repository. To access Jobs, click the Jobs button on the toolbar.

Jobs: Log in/Log out

To log in and start open a Jobs window, either click the Jobs button on the toolbar or go to the Jobs menu and click New Jobs Window. If a Jobs window without a connection is already open, the Connect button on the toolbar/from the context menu of the root of the navigation tree/on the Jobs menu will open the login screen. Then, follow the log in procedures - for more information, see Connecting to Documentum.

To log out, click Disconnect on the toolbar/from the context menu of the root of the navigation tree/on the Jobs menu.

The Jobs Interface Explained

Jobs List Displays the Documentum jobs, which can be colored differently according to their attributes (active jobs are colored differently than inactive jobs). This function is available in the Options dialog. You can sort the Job List by clicking the desired column header. Displayed jobs are subject to the selected node in the navigation tree and the filter settings.

Navigation Tree Click repository to display Repository jobs. Click All jobs to display all the jobs of all repositories with a valid session are shown. You can hide the navigation tree, in which case the last selection stays active and governs the contents of the job list.

Filter Filter settings additionally influence the contents of the job list.

Toolbar Displays the buttons for most frequently used functions.

Status bar Displays additional information.

Filter Management

Available filters are displayed as tabs on top of the job list. Selecting a tab activates the corresponding filter. To add an individual filter, click the Filter button. Possible settings are:

You can combine filter settings in any way. The individual filter will be added as a tab with the label Current Filter to the filter tabs and will be available for all repositories until Jobs is terminated.

To save an individual filter or make any other changes to existing filters, click Extras menu > Filter management tool.

Automatic Refresh

To configure the automatic refresh of the job list, go to the Options dialog.

Additional Information

Hover your mouse over single jobs to display additional information in a tooltip.

Jobs Functions

Job Control

To control jobs, use the the functions on the toolbar/the context menu of the job list/the Edit menu.

• Run a Job: Start the selected jobs.

• Run with Arguments: Starting a job with arguments first prompts you to change existing arguments (this option is deactivated when selecting multiple jobs). If you activate the Restore method arguments option after run is activated, you can reset changed arguments to their original values after the job is completed. If Jobs is closed or the session is terminated before the next job run is completed, you cannot restore changed arguments anymore (you will be notified in this respect.

• Stop a Job: When manually starting a job, it can take several minutes for the content server to execute the job, during which time you can stop the job. If the job was started using the Run with Arguments function, the original arguments will be restored immediately.

Job Management

Right-click the desired job for the following options:

• Create Job, then select the target repository. If called from the navigation tree, the job will be created in the selected repository. Next, configure the new job attributes. Note that new jobs will always be deactivated to prevent unwanted automatic execution.

• Copy Job either within the same repository or to another repository, then define the attributes in the properties dialog. If the job method object is not available in the target repository, you can decide to copy it as well. However, the source files of the job will NOT be copied. If necessary, you may need to copy these files manually. Note that copied jobs will always be deactivated to prevent an unwanted automatic execution.

• Delete Job, in which case the selected dm_job object is removed.

• Dump dm_job Object, then configure the new corresponding tab accordingly.

• Dump dm_method Object, then configure the new corresponding tab accordingly.

• Reset Job Status, which clears all the attributes of the dm_job object that indicate that the job is running. Sometimes jobs are no longer linked to a running process but the status is not cleared automatically and you can clean it up by executing this function.

Job Attributes

You can manage the following job attributes:

• Activate/Deactivate: Use the job list context menu or go to the Edit menu.

• Job Properties: Use the properties dialog available from the job list context menu or from the Edit menu. When finished, click Save & Run.

• Method Properties: Open and modify the properties of the dm_method object from the job properties dialog by clicking the Method Properties button next to the method name field.

Reports

You can reopen the latest job report by clicking the Report button on the toolbar. You can access up to 20 older versions of job reports from the context menu of the job list. Depending on the file type, reports will open in an external viewer. The Content Type Auto Detection can detect HTML reports and redirect them to open in your default browser.

In the XTended version, the Report button in the toolbar or the All Reports item from the context menu will open the report browser, which displays (to the left) all available reports of the selected job.

The functions on the report list context menu enable you to open reports in an external application, delete reports or truncate the reports list.

The following functions are available in the context menu:

Agent Exec Settings

The agent_exec process provides you with some parameters to influence job execution. To modify these parameters, go to Session menu>Agent Exec Settings.

Changes only take effect before the agent exec process is restarted on the Content Server.

Options

To access Options, which are are the central tool for adapting the features and functionalities of Jobs, go to the Extras menu.

Settings

Options Colors

Depending on their current status, Jobs can change colors.

The settings are additive. If an inactive job is colored with a foreground color only, and a successful executed job with a certain background color only, an inactive successfully executed job will be colored with the appropriate color combination. Otherwise, the priority in coloring is from top to bottom, as displayed in the dialog.

Clear the Colors checkbox to deactivate this option.

Columns

You can select the columns of the job list from all available dm_job attributes. In addition, the DOCBASE column displays the home repository of the job; the NOTIFICATIONS column displays the job notification settings.

Use the arrow buttons to sort the columns.

Auto Refresh

This function refreshes the displayed jobs and their properties in the job list. The refresh interval is freely selectable:

To reduce server activity, you can deactivate the auto refresh function after a certain time of user inactivity.

The API Command: filename

This command can be used anywhere within dqMan (API command, API scripts, functions etc.). The usage is the same as the API get command, but it returns a valid windows filename. This is very helpful for all types of file operations, like export.

Within the returned value all invalid characters are replaced by an underscore.

The DQL Administration Method: set_session_dd_locale

This method can be used to change the current session locale with a DQL command or a DQL script (within dqMan only).

Syntax: EXECUTE set_session_dd_locale WITH locale=’new_locale’

New_locale must be a valid locale in the repository where the command is executed in, e.g. en.

dqMan uses this command in the generated scripts of the functions Edit Attribute or Attribute Create Script.

The DQL Administration Method: count_sessions

This is a regular, but undocumented DQL Administrative Method to find the details of sessions, other than list_sessions and show_sessions.

Syntax: Execute count_sessions

The above DQL returns the following values:

• concurrent_sessions

• history_sessions

• history_timeout

• hot_list_size (active sessions)

• warm_list_size (timed out sessions)

• cold_list_size (free sessions)

This method is also available in the Server Session Statistics session function, available in the Functions menu.

Script Commands and Variables

dfc.Properties

The editor offers fast access to the configuration files of Documentum. It is available from the Edit menu and opens the first file found following the environment path. Also, the reference file dfcfull.properties will be open, if found, in which case all available commands are loaded from this file and will be available as value assistance that will appear either if dfc. is entered or by pressing Ctrl +Space.

How and when changes to the dfc.properties file will take effect depends on the dfc behavior. It may vary between different dfc versions.

The ACL Viewer

The ACL viewer displays ACLs for viewing and/or editing and is called either from the View (à View ACL) menu or from the context menu of the DQL result list.

It is activated only if an active session is available and either the selected objects in the DQL result list are ACLs or an ACL is assigned to them (like dm_document or dm_folder) and the attribute r_object_id is available in the list.

The ACL list contains all ACLs from the selected objects of the DQL result list. To view or edit properties, you can select an ACL from the list.

ACLs will only be added to the list once. Therefore, the number of selected objects can differ from the of the number of the ACLs in the list.

The Usage area informs about the usage of the ACL in the current repository.

Change permissions You can modify one or more selected permissions by clicking the Edit button. If more than one permission is selected, only the changes will be applied, unchanged fields will be ignored. For example, all groups can be assigned an extended permission without changing the basic permissions or the values of the other extended permissions.

Add permissions The Add button opens a dialog to add one or more new permissions. If an existing permission has been selected before, the settings of this permission will be copied to the dialog as default.

To search for a group or user, you can enter an expression (begins with) in the Search field. The Filter limits the displayed users and/or groups:

Additionally available for Template ACLs:

You can select multiple members from the list and add them at once with identical permissions. You can repeat this procedure until either the list of the users is empty or the dialog is closed.

Delete permissions You can delete the selected permissions by clicking the Delete button.

Save changes You can save your changes in two different ways:

• Save to ACL: Saves the changes to the ACL object. All objects that have been assigned this ACL are affected.

• Save to Object: Saves the changes to the object only, that is, a new ACL is created and assigned to the objects selected in the DQL result list. This function is only available if the object from the DQL result list is not an ACL itself. If more than one object with the same ACL is selected in the DQL Result List, a new ACL is created for each of them.

View group members If permissions are assigned to group names, the contained users and their resulting permissions can be displayed with the function Show users from the context menu.

You can select one or more groups.

In that list all users are displayed, together with their group names, the highest resulting basic permission as well as the aggregated extended permissions.

Copy permissions You can copy the selected permissions among different ACLs using the functions Copy, Cut and Paste from the context menu. The behavior is the same as using the common clipboard functions.

If a permission is inserted into an ACL which grants permissions to already existing users or groups, several options are available:

Content Restore

The Content Restore template allows the restoring of deleted non content-less objects (usually dm_document and its descendants).

The plugin adds two functions to the context menu of the DQL result list. They are available, if the list contains dmr_content objects.

Example query: Select * from dmr_content where parent_count=0;

Content File: View This function opens the content of the dmr_content object for viewing. It is allowed for all objects in the list, regardless if they are deleted (parent_count=0) or are still linked to a dm_sysobject.

Content File: Restore A dialog opens to allow some settings for the restore. The name is prefilled with the original filename taken from the attribute setfile. ACL and folder link is not mandatory.

Click Restore content to create a new object of the selected type and to place it in the selected folder. Attributes cannot be restored for technical reasons.

If more than one object is selected to be restored, the dialog is loaded with the data for the next object.

Go to the Extras menu>Options to adapt the features and functionalities of dqMan.

The last open category is saved when leaving the options dialog and restored on the next visit.

General

The General category has four subsections:

• Settings

• Login

• Shared Favorites

• Documentation

Settings

Login

Shared Favorites

Object Functions and the DQL favorites are stored locally, therefore every instance of dqMan uses its own data. However, Favorites can be shared if the full paths to the shared favorite files are supplied. The XML files which contain the favorites and Object Functions (DQL-Repository.xml and Functions.xml) need to be copied to a network drive for sharing. If the shared files are not available, local versions will be used instead.

Documentation

You can add and manage links to documents, URLs or program files to the Documentation menu using the function bar:

The API Command View

The DQL Command View

Settings

Code Editor: Grid Colors

Code Editor: Grid Hints

Grid Hints show additional information for single objects. They become faded in when the mouse is moved onto the row header (containing the row number).

Grid Hints can be defined for different object types. They consist of a hint template and translations. A Grid Hint template contains the following elements:

Translations turn values into readable designations. They are valid globally, that is, a translation for the attribute client_capability is valid for all defined Grid Hints.

Describe Options

These settings have already been described in #16.3.5.-describe-options.

The Repository Navigator

In the Repository Navigator, you can manage the Cabinets/Folder Tree, the Object Type Tree and the Group Tree.

• The Cabinets/Folder Tree

• The Object Type Tree

• The Group Tree

The Script Views

Functions

Functions are user programmable extensions. There are two different types of functions:

• Object functions, available from the DQL result grid, can contain references to the DQL result grid, as known from the Script Generator. On execution, the function is executed once for every selected object whereby the references are replaced with values from the current result grid.

• Session functions need a valid session and are executed only once. They cannot reference any values from the current session window.

dqMan is installed with a number of object and session functions that demonstrate the use of the extended functionality described below. If you have any more questions, send us an email at dqMan@fme.de.

Object Functions

This page displays all the available functions and provides tools to manage them, such as edit, copy a function, add and delete a function :

• Edit a function

• Copy a function

• Add a function

• Delete a function

• Copy a function

• Export selected functions to XML for exchange with other dqMan users.

• Import functions from XML file.

You can deactivate object functions without deleting them, in which case the function name is cleared.

The Object Function Assistant is used for easy creation and modifying an assistant.

Settings:

Options

Targets

On the second page (not available for option Execute as Subquery), you can define global variables. When calling the function, these variables are filled in either by the user's manual input or by queries from the repository, using API commands. The values of the global variables are valid for all objects processed in one function call.

In the variables, you can also reference column values of the DQL result list (for example, {r_object_id}). In this case, the function can be executed for single objects only. The option Allow multiselect is deactivated automatically.

The DQL query:

Select full_format from dmr_content where any parent_id = '{r_object_id}’ order by 1

results in a pick list that contains all available formats of an object. The column r_object_id must be contained in the DQL result list and only one object must be selected, otherwise this function is disabled.

To check the syntax of a DQL query, click the Check syntax button, if a valid session is available in any session window.

Field type:

The third page of the dialog either displays a textfield for the API sequence or for a DQL query (the Execute as Subquery option).

The Basic API Sequence Syntax

The API sequence consists of a batch of API commands similar to an API script. References to values of the DQL result list are enclosed in curved clips. During execution, those references are replaced with values from the result list.

fetch,c,{r_object_id} destroy,c,{r_object_id}

There are different placeholders to access the data of the result list:

Comments Each line beginning with the # character or with // is regarded as a comment line.

#fetch current object fetch,c,{r_object_id}

# destroy the current object destroy,c,{r_object_id}

Indenting For functions, indenting is allowed for all kinds of instructions. All leading spaces and tabs will be removed prior to executing the command. For multiline commands the same amount of leading characters will be removed from all lines as was done for the first line, except any valid char is found.

#Set ACL Domain Set,c,{r_object_id},acl_domain %ACL Domain%

If you create debug scripts, all indents are removed.

Variables There are three different kinds of variables:

• Global variables, defined in the object function assistant and filled once at function initialization. Their values are valid for all processed objects.

• Local variables, used within the API sequence, valid only for the processing of the current object:

• Predefined variables, as you can see here:

Example:

# set ACL name set,c,{r_object_id},acl_name %ACL Name%

# Set ACL Domain set,c,{r_object_id},acl_domain %ACL Domain%

# Save save,c,{r_object_id}

Script Commands Script commands extend the functionality of an object function. You can use placeholders or variables as parameters and they will be replaced by their values before executing the script command. Available script commands are:

Example for a collection loop:

%Collection%=readquery,c,select group_name from dm_group where any i_all_users_names = 'dmadmin'

#$Loop %Collection% %group_name% = get,c,%Collection%,group_name #$EndLoop

The handling of the collection is done by the #$EndLoop command. It is not necessary to add next or close commands.

The variable %LoopIndex<i>% does only exist within a loop and contains the current loop index, starting with 0. %Loopindex1% is the index of the first loop. %Loopindex2% would be the index of the second loop, if it is nested within the first loop.

Example for an attribute loop:

%id%= id,c,dm_document #$Loop i_folder_id(%id%) %Folder_ID% =get,c,%id%,i_folder_id[%LoopIndex1%] #$Loop r_folder_path(%Folder_ID%) %FolderPath%=get,c,%Folder_ID%,r_folder_path[%LoopIndex2%] #$EndLoop #$EndLoop

The variable %LoopIndex<i>% is incremented each time the #$EndLoop command is executed. It can be used as index for the repeating attribute values.

The DQL Query Syntax

In the DQL query text area any DQL query can be inserted that is executable by dqMan. This includes comments, template fields etc.

To reference any values of the underlying DQL result list, insert the attribute names in curved brackets. If any referenced attributes are not available in the DQL result list, the function is disabled.

The multiselect option is not available for this type of function.

17.6.2 Session Functions

Session functions are very similar to object functions. However, references to result list values, such as {r_object_id}, are not allowed; in addition, they are executed exactly once, independently from any selections made anywhere in the session window.

Go to the Functions menu to access installed session functions, which are only available if the active window is a session window with a valid session.

Security

The security page allows hiding of one or more advanced “hazardous” admin features. You must proceed with caution as these features can easily create great damage, for example, the recursive destruction of complete folder tree branches. To avoid any mishaps, these features can be deactivated.

There is no protection for this setting. Every user can show or hide these functions according to their personal needs.

You can access the Security options by clicking Extras menu>Options>Security.

This section provides information about the third party open source libraries used in dqMan. Provided bellow are the library names, the license under which they are being used and links to the specific version being used.