Sie sind auf Seite 1von 396

CARA v3.9.

0 for
Documentum
Configuration Manual

7 Mar 2016

This document is strictly confidential and may


be read only by licensed or evaluating
customers.
CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Table of contents

CARA Administration and Configuration Manual ......................................6


Configuration Overview .........................................................................6
CARA Configuration..................................................................................9
Control Panel ........................................................................................9
Tagging / Importing / Exporting Configurations ...................................10
User Capabilities .................................................................................13
View Management ..............................................................................25
Direct URL to a document ...................................................................82
Cabinet Display Label .........................................................................83
Dashboard configuration .....................................................................84
General configuration ..........................................................................95
Relation Type Configuration................................................................97
Document Format (Icon) Configuration .............................................101
Document Types (Icon) Configuration ..............................................102
Folder Types (Icon) Configuration.....................................................103
Sequences Configuration ..................................................................106
Staging Area .....................................................................................108
Lifecycle Configuration ......................................................................111
Scripts Library ...................................................................................123
Dictionary Manager ...............................................................................125
Opening a dictionary .........................................................................125
Creating a New Dictionary ................................................................126
Modifying a Dictionary .......................................................................130
Working with Dictionary values .........................................................131
Importing and exporting a dictionary .................................................133
Deleting a Dictionary .........................................................................134
CARA Default Dictionaries ................................................................135
Taxonomy Manager ..............................................................................139
Opening a taxonomy .........................................................................139
Creating a New Taxonomy................................................................140
Working with a Taxonomy .................................................................141
Importing and exporting a taxonomy .................................................143
Deleting a Taxonomy ........................................................................144
Registered Tables .................................................................................145
Modifying registered table data .........................................................145
Classification Configuration...................................................................148
Classification Definition .....................................................................148

7 Mar 2016 Page 2


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Classification Restriction ...................................................................151


Type, Lifecycle and Template Configuration .....................................154
Mandatory Properties Configuration .................................................157
Properties Initialization Configuration................................................160
Auto-values Configuration .................................................................163
Content Handling Configuration ........................................................166
Scripts Configuration .........................................................................168
MS Document Population .................................................................173
MS Word Field Merge .......................................................................174
Forms (Properties and Custom Actions) Configuration.........................175
Overview ...........................................................................................175
Viewing a Forms Configuration .........................................................176
Exporting a Forms configuration .......................................................178
Creating a Properties Forms Configuration.......................................179
Editing a Forms Configuration...........................................................180
Create a New Forms Configuration...................................................214
Check in from file / copy configuration ..............................................216
Deleting a configuration ....................................................................217
Properties DQL .................................................................................218
Document Category Configuration........................................................220
Creating, modifying and deleting categories .....................................220
Special case categories ....................................................................222
Audit Configuration............................................................................223
ACL Template Builder .......................................................................226
Security Configuration .......................................................................231
Linking Configuration ........................................................................233
Versioning Configuration ...................................................................236
Content Access Configuration...........................................................239
Status Change Configuration ............................................................241
Document Rendering Configuration ..................................................245
Legal Hold .........................................................................................247
DCN Configuration ............................................................................249
Automatic Change Notifications ........................................................250
Category Scripts................................................................................252
Purge Configuration ..........................................................................253
Task Configuration ................................................................................254
Task Types........................................................................................254
Task Templates.................................................................................258
Periodic Task Definition ....................................................................272
CARA Mail Configuration ......................................................................275
Mail Configuration .............................................................................275

7 Mar 2016 Page 3


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Notification Templates.......................................................................278
URL notes .........................................................................................283
Administration .......................................................................................285
Users .................................................................................................285
Groups ..............................................................................................290
Domains ............................................................................................295
Roles .................................................................................................299
User Activity Reporting......................................................................303
System Lock......................................................................................304
Object Types .....................................................................................307
Jobs and Methods .............................................................................310
Log Files – Viewing from CARA ........................................................322
User Preferences ..............................................................................323
User Preferences - attributes ............................................................324
Custom Actions .....................................................................................326
Overview ...........................................................................................326
Defining a Custom Action..................................................................327
Custom Actions – General Tab .........................................................328
Custom Actions – Definition Tab .......................................................329
Custom Actions – Variables Tab .......................................................339
Custom Actions – Restrictions Tab ...................................................341
Custom Actions – Options Tab .........................................................344
Custom Actions – Completion Tab....................................................345
Custom Actions – Export / Import .....................................................347
Custom Actions – Execute as Superuser..........................................348
Customizing CARA ...............................................................................349
Replacing classes .............................................................................349
Customizing the applet......................................................................351
Search configuration .............................................................................352
Asynchronous settings ......................................................................352
Scripts, DQL and API ............................................................................353
Using the API Command Feature .....................................................353
Using the DQL Screen ......................................................................354
Working with DQL Results ................................................................355
Saving DQL Searches.......................................................................356
Functions executed from custom screens.........................................357
Script Editor.......................................................................................359
Running Scripts as Jobs ...................................................................361
Script Examples ................................................................................362
Creating Help ........................................................................................368
Changing the appearance.....................................................................369

7 Mar 2016 Page 4


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Publishing Integration............................................................................370
Custom Content View ...........................................................................371
Appendices ...........................................................................................373
Procedure content .............................................................................373
CARA Jobs........................................................................................381
CARA Methods .................................................................................383
Date formats......................................................................................385
Some useful widgets .........................................................................388
Dumping objects and modifying properties .......................................389

7 Mar 2016 Page 5


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

CARA Administration and Configuration


Manual
Configuration Overview

This chapter This chapter provides a quick overview of the mandatory configurations
required in order to get started with CARA v3.9.0 for Documentum. This
chapter does not provide a step-by-step for each part of the configuration
– for that please refer to the relevant chapters in the rest of this document.

Please follow the steps in the mandatory section in sequence: this


chapter is designed to ensure that configurations that are required to
drive other configurations are done first.

Mandatory Overview
configurations The following requirements are mandatory, and should be done in the
following order.

Groups
Add users to the relevant groups (cara_*).

Custom doctypes and lifecycles


Ensure these are built using standard Documentum tools e.g. Composer.

User Capabilities
Set up the User Capabilities for the different roles in CARA.

View Management
Make changes to the views / add new ones as required.

General Configuration
Choose options in the General Configuration.

Dictionaries
Create all required Dictionaries including at a minimum those to be used
in the taxonomy which will be the docbase classification (see below).

Taxonomies
Create all required taxonomies, including one to be used as the docbase
classification (e.g. named “Main Classification”).

Continued on next page

7 Mar 2016 Page 6


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Configuration Overview, Continued

Mandatory Properties (Forms) Configuration


configurations Create all required properties configurations for the custom types you
(cont’d) have.

Type, Lifecycle, Templates Definition


Set the options in the Type and Lifecycle Definition.

Category Definition
Define any required Categories in the Categories Definition, at a
minimum one (e.g. “All Documents” where DQL is 1=1).

ACL Template Configuration


At least one ACL template is required even if none will actually be used

Security Configuration
Define the security for each category as required – if using the CARA
ACL Templates, then these have to be configured first.

Linking Configuration
Define the folder path rules for categories as required under the Linking
Configuration.

Document Rendering
Set up the Document Rendering configuration.

Audit Configuration
Add at least one category to the Audit configuration, even if no events are
set for that category.

Mail Configuration
Set up the mail configuration after making any changes to the email
templates as above.

Other Other configurations are optional.


configurations

Versioning Each time you modify a configuration in CARA, the configuration object
configuration is versioned automatically.

Continued on next page

7 Mar 2016 Page 7


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Configuration Overview, Continued

Drag and Drop In CARA v3.6.1+, drag and drop from the filesystem to the browser is
import with supported using HTML5. However, this is only available in the
HTML5 following browsers:

 Chrome 7+
 Firefox 4+
 IE 10+
 Opera 12+ (Version 12 for MacOS is disabled because their API
is unstable)
 Safari 6+

Changing the To modify the CARA logo on the Explorer window bar, replace the
CARA logo on the following file in the app server
Explorer window
…/images/cara_app_header.png

Java support In CARA prior to 3.7, JDK8 is not supported. With this release it is
supported. Please also note that some browsers are discontinuing support
for Java Applets – please refer to the individual vendors’ websites for
information.

7 Mar 2016 Page 8


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

CARA Configuration
Control Panel

What is the Control All CARA configurations apart from the few which are done on the app
Panel server level (see the CARA Installation Guide for details) are access from
the Control Panel. In the CARA Desktop Experience this is accessed
from the Start menu, or from its icon on the Desktop, and in the Explorer
experience it is accessed from the Control Panel Menu.

The Control Panel shows all configuration options grouped onto tabs
The rest of this manual details the configurations accessed from the
Control Panel.

7 Mar 2016 Page 9


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Tagging / Importing / Exporting Configurations

Overview All the configurations in CARA are held as objects in the folder /
subfolders under /System/Applications/CARA3/Config. One method of
migrating these e.g. from a Test to Production docbase is to use the
standard Documentum DocApp / DAR capabilities. See the CARA
Installation Guide for more information on this.

The other option is to use the built-in configuration export / import in


CARA, although it should be noted that you may still require a DAR or
DocApp if you want to move object types, lifecycles and other standard
(non-CARA) Documentum items.

To help manage configuration sets over time, you can tag the
configuration at any time – this applies a custom version label to each
current version of the configuration, allowing that tagged version to be
exported at any time, rather than just always exporting the latest.

Tagging a To tag a configuration, go to the Control Panel / Export Import and


configuration click on Configuration tags:

Click Tag Configuration and enter a tag.

Continued on next page

7 Mar 2016 Page 10


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Tagging / Importing / Exporting Configurations, Continued

Exporting a 1. From the CARA Start menu, open the Control Panel and click
configuration in on the Export/Import tab.
CARA 2. Click on the Configuration Export button.
3. Choose the particular tagged configuration to export if applicable
– if not selected, then the latest versions of each configuration will
be exported:

4. In the dialog that comes up, choose a location (and change the file
name if required) for saving the ZIP file to your machine:

Continued on next page

7 Mar 2016 Page 11


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Tagging / Importing / Exporting Configurations, Continued

Importing a 1. From the CARA Start menu, open the Control Panel and click
configuration in on the Export/Import tab.
CARA 2. Click on the Configuration Import button.
3. Select the ZIP file from your local machine which contains the
configuration to import.
4. The import is done, overwriting the previous configuration.

Note: the configuration, on import, is compared to the existing


configuration by a combination of the object properties and the checksum
of the content, so any configurations that are not changed from before are
not imported. Any configurations changed are versioned.

Locking a To lock a configuration object in order to avoid it being overwritten with


configuration new imports of the configuration zip (e.g. mail configuration settings),
object navigate to the object in the /System/Applications/CARA3/Config/* and
click on the object. Then select Tools / Script Editor and execute the
following script:

object.mark("LOCKED");
object.save();

This sets a version label of LOCKED. To reverse it, just remove this
version label.

Export The entire configuration settings can be exported to a document:


configuration 1. From the CARA Start menu, open the Control Panel and click
details to a on the Export/Import tab
document 2. Click on the Generate a Config Report button.
3. Select the folder on your local machine to which to export the
configuration document.

Once exported, you can export the document at a later stage and use the
Word Compare features to identify each configuration change made over
time.

7 Mar 2016 Page 12


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

User Capabilities

Overview User Capabilities define which menu items are available to which user
roles in CARA. There can be one or more User Capabilities defined, with
at least one being required (called Default and shipped with the product).
A role is a Documentum group where the group_class is “role”.

The User Capabilities are cached on user login to improve performance.

Adding a User From the CARA Start menu, select the Control Panel and click on
Capability General / User Capabilities.

1. In the screen that appears, click Add:

2. Select the desired role from the list and click Add:

Continued on next page

7 Mar 2016 Page 13


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

User Capabilities, Continued

Adding a User 3. Select or deselect the menus that the user should have access to,
Capability (cont’d) and click Save:

NOTE: you can search for user capabilities in the search box – enter
some string and keep hitting ENTER key to move to the next match.

Continued on next page

7 Mar 2016 Page 14


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

User Capabilities, Continued

User capabilities NEW ITEMS


explained
New Cabinet Create a new cabinet (user still requires New
Cabinet rights in Documentum as well)
New Folder Create a new folder
New Folder From Template Create a new folder + subfolders from a
template folder + subfolders in the Templates
cabinet
Create Document Create a new document (placeholder, blank,
template, copy)
Import Document Import a document
Duplicate Select a document and copy from the Edit /
Duplicate menu
New Document lifecycle state Allow users to select a lifecycle state in the New
selection Document screen
New document uniqueness Allow users to select whether the system will
validation validate the uniqueness of the names of
imported documentss
New Document / versioning Allow users to select to version existing
existing documents with the same name on import
Staging Area Import Allow users to import to the Staging Area
Batch Import Allow users to access separate Batch Import
menu item (not part of the regular File / New
screen where multiple import can also be done)
Create Template Create a new template document using the
placeholder, blank, template or copy options
Import Template Create a new template by importing
New Structure Create a new structure (user must be part of
cara_structure_creators group)
E-mail attachments extraction Allow users to extract e-mail attachments to
create new documents
VIEWING AND PROPERTIES
Properties Open properties
Properties widget - Edit button Show the “Open” button in the properties
widget, which will open the full properties
screen
Properties - Save button Display the Save (as opposed to Save and Close)
button in the properties screen
Properties with preview Open properties and a document preview
window from a single menu item

7 Mar 2016 Page 15


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Properties dump Create a dump of the document properties


Permissions Open a screen showing the details of the
document permissions
Permissions: custom settings for Allows buttons to create a custom ACL rather
documents than just select an existing ACL (documents)
Permissions: custom settings for Allows buttons to create a custom ACL rather
folders than just select an existing ACL (folder)
Preview Preview the primary content with a viewing
application such as ViewONE Pro or Brava!
(requires separate license)
Preview Panel Open thumbnail preview panel for selected
documents
View View the primary content
Download (using HTTP transfer) Use this option for content on devices without
Java applet support e.g. Apple devices
Open in Tabs Allows users to select to open the content in new
tabs in the same browser (image and PDF files
only)
Preview PDF Preview the PDF inside the browser
View PDF (no validation) View the PDF rendition – no validation of
presence of PDF rendition
View PDF (with validation) View the PDF rendition – no validation of
presence of PDF rendition
Request PDF Rendition Send PDF rendition request
EDIT, EXPORT, PRINT
Add to Favorites Add a document to your Favorites
Add to others’ Favorites Add a document to the Favorites of other users
Change Notification Request Request a change notification on an object
Export Export to the file system (subject to permissions
and content access configuration)
Export to Clipboard Export content to the clipboard (plug-in only)
Deep Export Export a folder structure including contents
Send To Email the document
Send as Email Attachment(s) Exports the document(s) as attachment(s) to an
(MSG) email (EML format)
Send as Email Attachment(s) Exports the document(s) as attachment(s) to an
(EML) email (MSG format)
Send as URL Email URL link(s) to the document(s)
Edit Checkout and open the file to edit
Checkout Checkout

7 Mar 2016 Page 16


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Checkin Checkin
Checkin: Description Switches on or off the Description field in the
checkin dialog
Checkin: Full Text Indexing Switches on or off a checkbox in the Checkin
screen to request Full Text Indexing
Cancel Checkout Cancel checkout
Delete Delete (via Trash Can, or without if superuser)
Print Open in the native application for printing
Print PDF Send the PDF rendition as silent print job to the
local printer
Controlled Print Print using the DocSecure Controlled Print
(requires separate license)
Checkout location change Allows users to change their default checkout
location after it is initially set
RENDITIONS
Preview Rendition Preview from the Renditions widget using
ViewONE Pro (requires separate license)
View Rendition View from the Renditions widget
Add Rendition Add a rendition in the Renditions widget
Rendition: page modifier selection Ability to show or hide the page modifier field
when adding a rendition
Remove Rendition Remove a rendition in the Renditions widget
RELATIONS
Add Relationship Add relationship
Edit Relationship Ability to modify the relationship details once
added
Annotations Import Import annotations file (FDF) for a document
Remove Relationship Remove relationship in the Relations Widget
and Relationship Manager
Relationship Manager Open the Relationship manager (functionality in
that subject to other capabilities)
TASKS
Add Task Add a task (CARA workflow)
Task saving (vs Issuing) Enables a button to Save a task as planned rather
than have to issue it immediately
Task recipients tree Enables the recipient selection to be displayed as
a tree with multi-select
Task completion: notify users Show or hide the fields to add ad-hoc
notifications on task completion

7 Mar 2016 Page 17


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Task Manager Open the Task Manager (functionality in that


subject to other capabilities). NOTE: task
initiators are automatically Task Managers
for their own tasks. (CARA workflow)
Task Template Manager Access to the Task Template manager
Task Report Open the Task Report (functionality in that
subject to other capabilities) (CARA workflow)
Out Of Office Settings Set Out of Office (CARA workflow)
Distribution Lists Create personal distribution lists (CARA
workflow)
DOCUMENTUM WORKFLOWS
Inbox: Tasks Access Documentum workflow inbox
(Documentum workflow) – this adds an icon to
the virtual desktop
Inbox: Notifications Access Documentum notification inbox
(notifications aside from Documentum
workflow ones)
Work Queues Display the Work Queues node for workflows
sent to a workqueue to which user has access
Task dialog: Other attachments Display or hide the “other attachments” node in
a workflow screen
Start Workflow Start Documentum xCP workflows
(Documentum workflow)
Workflow Reporting View reports on Documentum workflows
STRUCTURES
Publish Structure Create a published output from a structure
Section classification configuration Configure structure section nodes to have a
Classification for document classification pre-
population
VIRTUAL DOCUMENTS
Open Virtual Document Open (create) a virtual document from a
document or placeholder
Snapshots Viewing Ability to view, for a selected virtual document,
all snapshots
Snapshots Creation Ability to create virtual document snapshots
Snapshots Freezing Ability to freeze and unfreeze snapshots
Publishing Lock Create a publishing lock on virtual documents
Convert VD To Structure Convert a virtual document to a structure
SEARCHING
Advanced Search Open the Reporter / Advanced Search
Public Search saving Ability to save a search as Public

7 Mar 2016 Page 18


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Advanced Search facets Use the faceted searching with Documentum


6.7+
Last Advanced Search execution Provides menu item to rerun last Advanced
Search
Dashboard Access the Dashboards
Quick Search Display the Quick Search field
Quick Search for Folders Display a Quick Search field for finding folders
Search In Folder Display the Search in Folder field
Search Results: Highlight Unread Highlights (bold) search results until clicked on
in which case bold disappears
Trash Searching Search for deleted documents
WIDGETSPACE
My WidgetSpace Users can open the My WidgetSpace window
Users can configure what widgets/folders they
see in their My WidgetSpace experience
My WidgetSpace Configuration IMPORTANT: if the user has the ability to
configure Views (see later section) they will
have the ability to configure My WidgetSpace
regardless of this option.
Users can display the Home Cabinet widget in
Home Cabinet
the My Widgetspace window
Users can display the Favorites widget in the My
Favorites
Widgetspace window
Users can display the Change Notifications
Change Notifications
widget in the My WidgetSpace view
Users can display the Recent Items widget in the
Recent Items
My Widgetspace window
Users can display the Checked Out Items widget
Checked Out Items
in the My Widgetspace window
Users can display the CARA Workflow Intray
Intray
widget in the My Widgetspace window
Users can display the Documentum workflow
Documentum Inbox
Inbox widget in the My Widgetspace window
Users can add any folder as a widget in the My
My WidgetSpace: folder selection
Widgetspace window
Users can add any SnapList as a widget in the
My WidgetSpace: SnapLists
My Widgetspace window
Users can add the Staging Area in the My
Staging Area
WidgetSpace window
OTHER REPORTS
Status Manager Open the Status Manager (functionality in that
subject to other capabilities)

7 Mar 2016 Page 19


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Audit Trail Report Open the Audit Trail Report (functionality in


that subject to other capabilities)
Annotation Report Open the Annotations Report (functionality in
that subject to other capabilities)
EXPLORER OPTIONS
User Experience Switch Allow users to toggle between Explorer and
MyWidgetSpace experiences without logging
out and in again
View change Enable or disable the Document View dropdown
Double-click action change Enable or disable a user from changing the
default double-click action for the selected View
Cabinet Restrictions Allow users to restrict their view to certain
cabinets
My Desk Node Display or hide the My Desk node
Home Cabinet Node Display or hide the user’s Home Cabinet
Cabinets Node Display the Cabinets node at the top level of the
tree
Favorites Node Display or hide the user’s Favorites folder
Change Notifications Node Display or hide the Subscriptions Node
Recent Items Node Display or hide the user’s Recent Items folder
Checked Out Docs Node Display or hide the user’s Checked out
documents folder
Saved Searches Node Display or hide the Saved Searches node under
the Search Results in My Desk (provides quick
access to saved searches)
Tasks Node Display or hide the user’s Tasks node under My
Desk (CARA workflows)
Dimensions Node Display or hide the Dimensions node
Configuring Dimensions Enable or disable users to configure their own
Dimensions
SnapLists Node Display or hide the SnapLists node
Staging Area Display or hide the Staging Area node
Expand All Nodes Allow the user to have the Expand All Nodes
menu
Clipboard Allow the user to copy items to the Clipboard
TOOLS
eCTD Viewer Adds the menu to open the eCTD viewer
DQL Open the DQL screen (subject to Documentum
rights, e.g. less than Sysadmin can only execute
SELECT)

7 Mar 2016 Page 20


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

API Open the API screen (subject to Documentum


rights)
Script Editor Opens the Script Editor to test script syntax
CONFIGURATION
Lifecycle Access to configure Lifecycles
Views Access to configure CARA Views
Dashboards Access to configure CARA Dashboards
Custom Actions Access to configure Custom Actions
Script Library Access to the Script Library
Folder Types Access to configure CARA Folder Types
Document Types Access to configure CARA Document Types
Relation Types Access to configure CARA Relation Types
Task Types Access to configure CARA Task Types
Periodic Tasks Access to configure CARA Periodic Tasks
Mail Settings Access to configure CARA Mail Settings
General Access to CARA General configuration
Staging Area Access to CARAStaging Area configuration
Dictionaries Access to CARA Dictionaries
Taxonomies Access to CARA Taxonomies
Registered Tables Access to manage registered table data
Forms Access to CARA Properties configuration
Sequences Access to CARA sequences configuration
Classification Definition Access to CARA Classification Definition
configuration
Classification Restrictions Access to CARA Classification Restrictions
configuration
Classification Type and Lifecycle Access to CARA Type and Lifecycle
configuration
Classification Mandatory Access to CARA Mandatory Properties
Properties configuration
Classification Property Access to CARA Property Initialization
Initialization configuration
Classification Auto Values Access to CARA Auto Values configuration
Classification Scripts Access to CARA Classification Scripts
configuration
Classification Content Handling Access to CARA Content Handling
configuration

7 Mar 2016 Page 21


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Classification Properties Access to CARA Properties Extraction


Extraction configuration
Classification Properties Access to CARA Properties Population
Population configuration
Categories Definition Access to CARA Categories Definition
configuration
Categories Audit Access to CARA Audit configuration
Categories ACL Template Builder Access to CARA ACL Template Builder
configuration
Categories Security Access to CARA Security configuration
Categories Linking Access to CARA Linking configuration
Categories Versioning Access to CARA Versioning configuration
Categories Content Access Access to CARA Content Access configuration
Document Rendering Access to CARA Rendering configuration
Legal Hold Items Access to CARA Legal Hold Items
configuration
Automatic Change Notifications Access to CARA Categories Automatic Change
Notifications configuration
Categories Scripts Access to CARA Categories Scripts
configuration
Purge Config Ability to configure the purging job
ADMINISTRATION
Users Ability for non-System Administrators to
manage users
Groups Ability for non-System Administrators to
manage groups

7 Mar 2016 Page 22


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

User Capabilities, Continued

Editing a User From the CARA Start menu, select the Control Panel and click on
Capability General / User Capabilities.

1. In the screen that appears, select the Capability to edit, and click Edit:

2. Select or deselect the menus that the user should have access to, and
click Save:

Continued on next page

7 Mar 2016 Page 23


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

User Capabilities, Continued

Removing a User From the CARA Start menu, select the Control Panel and click on
Capability General / User Capabilities.

1. In the screen that appears, select the Capability to edit, and click
Remove:

2. Click OK to the confirmation. Note that you cannot remove the


Default Capability.

Important Note User Capabilities are cumulative. In other words, a user will get all
the menu items available under all the roles in which they are a
member.

7 Mar 2016 Page 24


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management

Overview Document vi``ews drive a wide range of functionality within CARA –


multiple views can be set up (there should be a minimum of one, named
Default, however). The views drive which types, properties, columns,
filters and double-click actions are being performed. Users can select to
switch views themselves. Views are often used to make appropriate
information available to different groups / units within an enterprise.

Adding / editing / From the CARA Start menu, select the Control Panel and click on
removing a View General / View Management.

1. In the screen that appears, click Add (or select an existing View and
click Duplicate if you wish to create a new view based on an existing
one):

2. The View screen appears.


The steps for editing a screen are as above, except select a view and click
Edit.
To remove a view, select it and click Remove. Click Yes to the
confirmation.
Working with View settings is described below.

Continued on next page

7 Mar 2016 Page 25


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

View Management The home screen for a view shows a set of icons giving quick access to
Home screen all the parts of the view that can be configured. This was previously laid
out as tabs. On this home screen, you also set:

 View name: this is a free text field to assign a name to the View.
 Type: this is the object type on which the view is based – this drives
the list of available properties for example.
 For form usage only / hidden in Explorer – view for use in Object
Grids in Forms, and not available in the Explorer for user selection.

Continued on next page

7 Mar 2016 Page 26


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Columns

The settings are as follows:


 Columns: this is the list of columns available for users.
o To add a column, click Add. A popup will appear in
which you enter:
 The attribute name (internal name, the Label from
the Documentum data dictionary will be used for
the display) – type in a name if using an attribute
from a subtype of the type selected for the View
 The label – if you want to override the default
Documentum attribute label
 The alignment – left, center, right

Continued on next page

7 Mar 2016 Page 27


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Columns (cont’d)  Whether the attribute should be sortable. If the


attribute is sortable AND is not an attribute on the
type itself, then the sorting will be done on the app
server.
 The width (in pixels)
 The Format column allows you to specify “d” for
date fields if you want just the date, not the
date/time:

or to specify a particular format e.g. YYYY-MM-


DD HH:mm. If you do not specify anything, the
locale settings for the logged in language will be
used.
 Whether it is Visible or not
 Whether to use a display alias from a particular
Dictionary (these must be used in combination)
and also whether to sort by alias value
 Click Save to save the new attribute

o To remove an attribute, select the checkbox at the


beginning of the appropriate row(s) and click Remove

7 Mar 2016 Page 28


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

o To re-order attributes, select the checkbox at the beginning


of the appropriate row and click the Up or Down arrows

 Sort column: which of the displayed attributes should be used for


sorting by default (users can change the sort order once they login).
 Sort direction: whether the sorting is ascending or descending

A shortcut from v3.5.1 upwards is to click Add Multiple which then


allows you to select multiple attributes to add in one go.

 Results limit: to improve performance, set a limit in here for the


results to be displayed on e.g. accessing a folder. Note that for larger
folders users can still access different documents by a combination of
sorting, filtering, grouping and so on. Leaving this field empty will
impose no results limit.
 Page size: the values that will be available for users to choose from in
determining how many documents will be displayed per page (folder
view or search results view). To add a new Page Size, click Add,
enter an integer, and click OK.

To remove a page size, select it and click Remove.


 Select whether to disable List view and/or Thumbnails and / or
Carousel.

NEW in v3.6.1 - If column is based on a dictionary and alias values end


with ".png" or ".gif", the icon from the images\icons\16x16\ folder should
be displayed instead. Icon size has to be 16x16px. Alias should be set to
"-" if no icon should be displayed.

Continued on next page

7 Mar 2016 Page 29


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Row styles CARA offers the ability to highlight important items based on conditions
which can be configured in this tab. You can either change the colour of
any row which meets the conditions, or add a custom icon to those items.

ROW STYLES
To add a custom row style, click Add in the Custom row styles section
of the Row Styles tab.

Continued on next page

7 Mar 2016 Page 30


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Row Styles You can enter a condition in the Conditions window, but note that it is
(cont’d) NOT regular DQL and only accepts the following kind of conditions:

1. A single condition has the following for: <attribute> <operator>


<value>, e.g. a_status=Draft
a. Attribute – object attribute name or a computed
attribute”_is_recent” that returns whether the document is in
the Recent Items
b. Operator – on the listed below
c. Value – attribute value without quotes.
i. Boolean attribute - should be “true” or “false” (without
quotes) optionally 0 or 1
ii. Date attribute – NOW value can be used to point to the
current date and time
2. A single condition can use one of the following operators:
a. Equals =
b. Not Equals <> or !=
c. Less than(can be used for dates and numbers) <
d. Bigger than(can be used for dates and numbers) >
3. Conditions can be combined with the following operators:
a. && - means AND
b. Line break - means AND
c. || - means OR

Do not use quotation marks to enclose your conditions. For Boolean


values use true or false rather than 1 or 0.

then select a style from the CSS style name dropdown.

ROW ICONS
To add a custom icon for documents meeting a condition, click the Add
button in the Custom row icons section of the Row Styles tab.

7 Mar 2016 Page 31


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Type a condition into the Conditions box.


The conditions can be as for the row style above.

Note that you can also define a bullet to be placed on top of the existing
icon. E.g. choosing the bullet_red above will label all draft documents
with a red dot:

7 Mar 2016 Page 32


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

The following conditions are also available to be used:


_is_recent=true
_is_favorite=true

Continued on next page

7 Mar 2016 Page 33


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Filters There are Global Filters and Attribute Filters available. Global Filters are
selected by the user at the bottom left of the Explorer window and apply
to all area (folders, Dimensions, My Desk) apart from Search Results and
SnapLists:

Attribute Filters are presented as dropdowns above a list of documents in


folders or My Desk view, and when selected apply ONLY to that view
until another selection is made in the tree, at which time they are reset:

Continued on next page

7 Mar 2016 Page 34


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Filters (cont’d) If Global Filters are not desired for a view, check the box to Hide Global
Filters panel. Otherwise, w`hen configuring Global Filters, the filters
can be set up in groups, where each group will contain one or more filters
which are perhaps related:

GROUPS

To add a group, click one of the Add Group buttons. The new (empty)
group will appear. To remove a group, click on the Remove Group
button UNDER the group you wish to remove.

FILTERS

To add a filter, click on the Add Filter button UNDER the group to
which you wish to add a filter. Enter a Name (including choosing from a
multi-lingual label), a DQL Condition (from after the “where” in the
predicate e.g. a_status = ‘Approved’) and specify if the filter is enabled
or not. Also specify if it is Permanent (ie cannot be checked / unchecked
by the user) or not. Then click Save.

Continued on next page

7 Mar 2016 Page 35


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Filters (cont’d)

To remove a filter, checkbox the filter and click on the Remove Filter
button UNDER the group where you wish to remove the filter. To re-
order filters, checkbox the filter and use the UP or DOWN arrows.

IMPORTANT NOTE: Filters in the same group are treated on an


“OR” basis so to have two filters working on an AND basis ensure
they are in different groups.

To set Attribute Filters, navigate to the 2nd tab, and click to add a filter,
entering the attribute information:

Continued on next page

7 Mar 2016 Page 36


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Properties The Properties configuration allows you to select which properties will be
displayed in the Properties widget for this View:

To add properties for the parent type selected for the View, select them
from the left and move them to the right using the single arrow, or move
them all using the double arrow.

To remove properties, select them from the right and move them to the
left using the single arrow, or move them all using the double arrow.

To re-order properties on the right, select them and use the UP or DOWN
arrows.

To add properties for subtypes of the parent type selected for the View,
click on the Add button in the Type Dependent field. Select a subtype
from the dropdown:

7 Mar 2016 Page 37


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Then select the properties required from the left and drag & drop /
double-click / use the arrows to move them to the right. Do the opposite
to remove them. These properties will only be displayed in the widget
when you select a document of this subtype:

NOTE: if a particular subtype is selected, then the widget will ONLY


show those properties listed in the type-dependent section, so you made
need to add some standard attributes (e.g. object_name) again.

Continued on next page

7 Mar 2016 Page 38


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Dimensions The Dimensions configuration allows you to define the behavior for the
Dimensions. On the Available attributes tab, you can select whether to
Disable dimensions completely for the view (the node will appear but the
user cannot expand it):

By default, the available properties shown under the Dimensions are ALL
properties available on the base type of the View. To restrict to certain
properties only, select them from the left and move them to the right
using the single arrow, or move them all using the double arrow. To
remove properties, select them from the right and move them to the left
using the single arrow, or move them all using the double arrow.

On the Levels tab, you can set the Required levels of Dimensions. If left
blank, there are no required levels.

New in v3.6.1: If you set the value to -1, then on clicking on the top level
of Dimensions, you will have all documents displayed. Note that this can
cause a performance problem so use it carefully.

7 Mar 2016 Page 39


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

New in 3.8.1 – you can now use date fields, the dates will be shown in the
format yyyy-mm.

If you set at a particular value, then that will be the minimum number of
levels a user must set to display some documents (e.g. if you choose 3,
then only when clicking on a node at level 3, 4 or 5 will any documents
be shown) – this reduces the number of queries / length of queries that
might involve some of the levels:

To set certain levels to a Default value, select the value from the
dropdowns in the Manual Dimensions section.

Users can be presented with defined “Dimensions sets” – collections of


dimensions. In this case, the sets will display under the Dimensions node,
and the user will NOT have the ability to manually configure the
Dimensions in these sets:

To create a set, click Add:

7 Mar 2016 Page 40


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Enter the following information:


- Set Name: name that should appear for the user, including a
multi-lingual value
- Required levels: Number of levels down a user must click before
documents are searched for and displayed (to help performance)
- DQL Filter: Additional DQL filter to apply to the set
- Levels 1-5: attributes to use for the various levels (minimum 1)
- Define whether to Link levels by attribute indexes / Enable row
based query – what this does is allow you, where using a grid
such as the image below, to link values as defined in the grid:

- Restrict to the selected users/groups: whether the set should be


available for all users of the view (if left blank) or restricted

You can also select the checkbox to Sort dimension sets alphabetically.

Finally, on the Settings tab, you can specify queries behind individual
Dimensions:

7 Mar 2016 Page 41


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Instead of querying all values of all documents in order to build and


display Dimensions, it is possible to drive them from a table/view.
Simply enter the name of the table (which might be a registered table of
all values available for example dm_dbo.products) and this can greatly
speed up performance of Dimensions.

Without qualification, the Dimensions will show all values of each


attribute. However, it is possible restrict those in two ways. The first is a
DQL condition that applies to all Dimensions (including values if pulled
from a table or view as above), and the second is to filter each attribute by
a particular query:

Note that the query for the Dimensions overall is from after the “where”
part of the DQL select statement. For individual attributes, it is a full
DQL statement.

In the same screen as adding a query filter for each attribute, you can

7 Mar 2016 Page 42


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

select to group by the first few characters of a Dimension – particularly


good in handling large lists:

This also allows for using Display Aliases for attributes where they exist.

Results in:

Continued on next page

7 Mar 2016 Page 43


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Menu The Menu configuration allows you to specify which menu items should
appear on right-click menus for documents and for folders.

If the fields are blank, then the application default settings are used.

Otherwise, you can click Add Actions for each section, and then using a
screen similar to the User Capabilities, select individual items to add /
remove. Note that in this screen you will also see any Custom Actions
which have been defined.

7 Mar 2016 Page 44


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Once you click OK to this screen, the items will populate into the main
screen.

You can now click to Add separators at particular places, and drag and
drop items to re-order them (including separators).

Continued on next page

7 Mar 2016 Page 45


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Toolbar The Toolbar configuration allows you to specify which toolbar items
should appear, as well as whether the toolbar icons should be in a single
row or two rows, and whether the button itself or button + label should be
displayed.

To manage the toolbar items, proceed in the same way as for the Menu
tab items above. Again, leaving the field empty will use the application
defaults.

To set a single row vs two rows, check the box as appropriate. The
results will be:

Or

7 Mar 2016 Page 46


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Check the box to display the labels as well as the button, the result will
be:

Continued on next page

7 Mar 2016 Page 47


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

SnapLists This SnapLists configuration allows you to create SnapList nodes


including defining the queries and filters, that will show up in the left
hand tree or filter bar for users of the view.

To Add or Edit a SnapList, click the Add button or select an existing


SnapList and click the Edit butt:

On the General tab, enter the information as required:


 Label (Name of the SnapList Node) including using multi-lingual
labels
 Path (Path to the SnapList node, a similar concept to folders, e.g.
a way to group similar SnapLists together under one parent node)
 Location: whether the SnapList should appear under the
SnapLists node or the My Desk node. If selecting My Desk, you
can then select whereabouts in My Desk it should appear.
 Icon (icon for the SnapList)
 Type (base object type for the query, MUST be dm_sysobject or a
subtype of that)
 All Versions (whether all versions of documents should be
returned in the query)
 Qualification (DQL query to collect the objects – this can include
using ‘${filter}’ where the Search In Folder field value is
substituted, or also DQL keywords e.g. USER)

NOTE: the query should be enclosed in a pair of parentheses.


 Load before filter execution this means that when clicking on a

7 Mar 2016 Page 48


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

SnapList node, the user will get all results showing without filters.
If unchecked, then the query is not run until some filters are
selected. Using this helps with performance of larger SnapLists.
 Results limit this will limit the number of results shown (leaving
it empty will not limit the results).

The columns tab allows you to specify the columns that will be shown,
and the default sorting. Please refer to the columns management on the
General tab of the View Management above for information.

A shortcut from v3.5.1 upwards is to click Add Multiple which then


allows you to select multiple attributes to add in one go.

7 Mar 2016 Page 49


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

The Filters tab allows you to create subnodes below the SnapList which
will group or filter results. To Add a filter click Add, to Edit a filter
select an existing Filter and click Edit:

7 Mar 2016 Page 50


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Give the filter a name, an icon, and choose an attribute value. Each
distinct value will be used for either a filter dropdown on the toolbar, OR
(if the Display as node option is selected) as a node one level beneath the
SnapList. If you select a date attribute, you can choose to group the dates
by Year, Quarter, Month, Week or Day:

The Security tab allows you to define if the SnapList should only be
available to particular users / groups or (if left blank) to everyone who has
access to the View:

Continued on next page

7 Mar 2016 Page 51


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

New Item This configuration allows you to create shortcuts for the “New
Shortcuts Document” wizard. For example, if users often create a document from a
particular template using particular Classification settings, this can be
preset as a New Item Shortcut. Users will see this on the Toolbar and/or
File New menu:

To create a new shortcut item, click Add.

In the screen that appears, enter a Name for the shortcut (this is used
internally) and a display Label (this becomes the menu item name and/or
the toolbar button tooltip) either as text or a selection from the multi-
lingual Display Labels dictionary.

7 Mar 2016 Page 52


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Select an Icon for the item (this will display in the menu and/or Toolbar)
and also select whether you want to add the item to the Toolbar
(otherwise it is added as a menu only).

Select whether the item is to create a new Document or Structure (which


will be based on the Classification) or a new Folder or Other Object
(which will allow selection of a non-classification-based object type):

Depending on what you select above, the options visible below will
change. For New Document and New Structure, choose a Classification
for the item (if you do not select all levels, the user will be required to
complete them during document creation):

OR for Folders / Other Objects select an object type:

For creating a folder from a template (which picks up a list of template


folders in the /Templates / CARA Folder Structure Templates folder),
select the folder template from the dropdown and select whether to
include content or not.

7 Mar 2016 Page 53


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Select the kind of document creation (NOTE: if you select only one, the
user cannot change it, if you select multiple the user gets the choice of the
items during document creation):

If you select Blank and/or Template, there will be an option to select the
Blank and/or Template:

On the Restrictions tab, select any group for which this item is available
(NOTE: if you do not select any groups, then it is available for all users,
depending on the Classification Restrictions settings). You can also enter
one or more paths (using the format /Cabinet/Folder/Folder) to restrict the
use of the New Item Shortcut to particular locations:

Click the button to access the list of users / groups – move the desired
ones from left to right using drag & drop / double-click / the arrows and
click Save:

7 Mar 2016 Page 54


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

To Edit an existing shortcut, select it and click Edit and follow the steps
above. To Remove a shortcut, select it and click Remove. Click Yes to
the confirmation.

Finally, you can also predefine some Property Initialization rules. The
definition of these is the same as regular Property Initialization
configuration, please refer to that section of this guide:

7 Mar 2016 Page 55


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

You may also use ${var} syntax in the property initialization, e.g.:

object_name=${i_cabinet_id}

Continued on next page

7 Mar 2016 Page 56


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

In-Tray / Inbox The In-tray / Inbox configuration allows you to specify how your CARA
workflows In-tray or your Documentum Inbox look.

The In-Tray tab allows you to select which columns will be displayed in
the various task folders in the tree view, and also whether to group tasks
by Type or Priority:

 Task Grouping: this will group the Tasks folders by type or priority
 Columns: this is the list of columns available for users.
 To add a column, click Add. A new row will appear. Enter:
o The Attribute name
o The Label if you want to override the default
o The Alignment – left, center, right
o The Width (in pixels)
o The Format e.g. “d” or YY-MM-DD for date fields
o Whether it is Visible by default or not

7 Mar 2016 Page 57


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

 To remove an attribute, select the checkbox at the beginning of the


appropriate row(s) and click Remove
 To re-order attributes, select the checkbox at the beginning of the
appropriate row and click the Up or Down arrows
 Sort column: which of the displayed attributes should be used for
sorting by default (users can change the sort order once they login).
 Sort direction: whether the sorting is ascending or descending
 Open the Task Manager after saving / issuing tasks: Previously,
the Task Manager was always opened in CARA on save or issue of
tasks, and this can now be controlled through this configuration.

A shortcut from v3.5.1 upwards is to click Add Multiple which then


allows you to select multiple attributes to add in one go.

The Documentum Inbox tab gives you the options for displaying the
contents of your inbox for Documentum BPM workflows:

NOTE: the options to Hide Delegate button and Hide Repeat button
will override the Documentum workflow setting for that workflow (which

7 Mar 2016 Page 58


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

would e.g. show the delegate button if delegation were an option). The
other options (Hide Info tab, Hide Comments tab, Hide History tab,
Hide Upcoming tab) allow you to hide some of the other standard tabs in
the Workflow screen.

The Standard option will display the list of work items, which have to be
double-clicked in order to open them (see the CARA User Manual).

The option to display with attachments allows you to define columns


and sorting as elsewhere in CARA, and instead of showing the work item
in the list, shows the attachment to the workflow. However, this does not
show all the attachments groups by workflow (unless you use some
column of metadata to provide the grouping).

Continued on next page

7 Mar 2016 Page 59


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Dialog Settings The Dialog Settings configuration allows you to select which columns
will be displayed in the following windows:
 VD Manager
 Status Manager
 Audit Report
 Task Manager

To customize one of the windows, go to the appropriate tab, and select


the checkbox:

 To add a column, click Add. A new row will appear. Enter:


o The Attribute name
o The Label if you want to override the default
o The Alignment – left, center, right
o The Width (in pixels)
o The Format e.g. “d” or YY-MM-DD for date fields
o Whether it is Visible by default or not
 To remove an attribute, select the checkbox at the beginning of the
appropriate row(s) and click Remove
 To re-order attributes, select the checkbox at the beginning of the
appropriate row and click the Up or Down arrows
A shortcut from v3.5.1 upwards is to click Add Multiple which then
allows you to select multiple attributes to add in one go.

Continued on next page

7 Mar 2016 Page 60


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Search config The Search config configuration allows you to define searches for users.
The General tab allows you to set

1) Whether to Default Quick Search to searching for Documents or


Folders
2) Whether to hide the Ranking column
3) Whether to re-execute the search when a user refreshes the pane
showing the search results
4) Whether the sort order follows the user’s preferences, or always
defaults to using the Ranking
5) Sort order to define the results to return in the case results are
truncated to a particular number, and whether that is ascending or
descending. If not configured, not added to the results “order by”
setting

Search config – Choose whether the Documents Quick Search should be based on Full
Documents Quick Text Searching or Attribute Searching. If it is based on attribute
Search searching, select the attributes which will be searched. ONLY STRING
attributes can be used.

Additionally, select whether the search operator should be Contains or


Equals or Starts with.

If you select to Allow typeahead, then the typeahead in the Quick Search
field will result in a filtered list of documents being shown as you type
(this field is used in other places such as the New Document screen /
Copy document option, the Add Relationship screen and so on).

If you check this box, you can define the format of the typeahead
(whether the dropdown shows just the name of the document or
additional attributes). Leaving the box blank will result in the application

7 Mar 2016 Page 61


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

default being used, which is shown below. Modify this using the same
format / syntax for additional attributes:

<h3>{object_name}<span>{r_creation_date_txt}<br/> by
{owner_name}</span></h3>{r_version_label}<br/>{locations}

Note the use of “locations” to show folder paths, and _txt after a date
field to show a date field as text.

The option Search in version labels allows you to specify particular


version labels to be returned, typically “CURRENT” or perhaps
“EFFECTIVE”.

A tooltip (including using a multi-lingual alias) can be set so the user


knows what the behavior of the search field is (e.g. “Search by Name,
Title and Product ID”)

Continued on next page

7 Mar 2016 Page 62


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Search config – Choose whether the Folders Quick Search should be based on Full Text
Folders Quick Searching or Attribute Searching. If it is based on attribute searching,
Search select the attributes which will be searched. ONLY STRING attributes
can be used.

Additionally, select whether the search operator should be Contains or


Equals or Starts with.

Search in Folders Choose whether the Search in Folder should be based on Full Text
Searching or Attribute Searching. If it is based on attribute searching,
select the attributes which will be searched. ONLY STRING attributes
can be used.

Additionally, select whether the search operator should be Contains or


Equals or Starts with.

Continued on next page

7 Mar 2016 Page 63


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Advanced Search
configuration

To add an Advanced Search configuration (one per type or subtype of the


type on which the view is based), click Add, select the type you wish to
base the search configuration on, and click Add:

To edit the search definition for a type, select the type and click Edit. In
the screen that appears, the Type name is not changeable, but the Type
Label can be changed from the value which is picked up from the
Documentum data dictionary:

7 Mar 2016 Page 64


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

NOTE: the type can also be a folder type.

To add an attribute as searchable, click Add, select the attribute you wish
to add, and click Add:

The new attribute will be displayed in the previous screen:

Continued on next page

7 Mar 2016 Page 65


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Advanced Search To edit the settings, double click on the attribute or click Edit:
configuration
(cont’d)

The Attribute Label can be modified here from the default defined in the
Documentum data dictionary.

NOTE: using the dropdown, you can select a value (if one is defined)
from the Display Labels dictionary, which allows the label to show in
different languages according to the language alias. See the section on
Dictionaries for more information.

The Default Operator allows you to specify what the default operator
should be when a user selects this attribute for searching.

Enter any Value assistance as required.

 Query: Enter the DQL statement which will provide the list of
drop-down values for the user to select from:

7 Mar 2016 Page 66


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Note: The DQL statement can contain variables and even conditional
variables, e.g. select name from table [where category='${category}'];
typed in this form, the search when there is no category selected will
simply be “select name from table”.

For example

select name from table [where category=${category}]

(note – no quotes required in the example above around the ${category})

name = column in query table (registered or Documentum Type)


category = another column in query table (registered or Documentum Type)
and ${category} is another attribute in the search config
and anything inside [] is removed if ${} value is empty

THIS [where] syntax is not supported in the Portal so for the Portal saved
search do not use this.

It is also possible to use the ${filter} syntax, as for Forms value


assistance, so the user can filter the value assistance picklist in the search
e.g.

select department_name from custom_document [where


lower(department_name) like ‘%${filter}%’]

You can also reference any of the attributes used in the Classification,
without having to explicitly add them as search fields.

Continued on next page

7 Mar 2016 Page 67


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Advanced Search  Value list: enter a set of values on separate lines which will
configuration provide the list of drop-down values for the user to select from:
(cont’d)

 Dictionary: select the dictionary which will provide the list of


drop-down values for the user to select from:

Also, if there are any aliases defined, select the appropriate alias
(or the option [per user locale]).
 Click Save. Add / edit other attributes as required.

You can use value assistance e.g. from Dictionaries for integer attributes.

To remove an attribute, select it and click Remove. To remove a type


search, select it and click Remove.

Note: if there are no searches configured, CARA will display all


available attributes and types in the search screen for that view.

Continued on next page

7 Mar 2016 Page 68


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Other search If a search has been saved, you can navigate it to select it, and that saved
configuration search definition becomes the Default search screen opened:
options

NOTE: for the CARA Portal, if using a search, please save a search
called “Portal” to be used as the default layout on arriving at the
portal screen.

Choose whether to allow searching on Classification only, if not then


Type will be available as well.

Choose whether to allow searching on Type only, if not then


Classification will be available as well.

Select whether to hide


 The “Ranking” column in the search results.
 The “Link Criteria” option
 The “All versions” checkbox
 The “Case sensitive” checkbox

Continued on next page

7 Mar 2016 Page 69


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Search facets If you are using Documentum 6.7+ with xPlore, then faceting is available
in your search results. To configure the facets, select attributes from the
list of available values on the left and move them to the right (please
ensure that the requisite configuration for faceting and which attributes
can be used is set up according to the Documentum documentation).

Custom Search You can replace the standard Advanced Search with a custom search,
using the Forms capability in CARA to define the form. To do this, go to
the final tab of the Search configuration:

Continued on next page

7 Mar 2016 Page 70


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Custom Search First, click Add in the top box to add one or more variables.
(cont’d)

Then, click the button to create a Form, and follow the steps as for the
Form configuration in this guide to build the form.

Finally, add mappings from any variables to properties in the bottom


section:

Once saved, the Custom Search will replace the standard Advanced
Search when the user clicks to open a search.

NOTE: any variable can have a default value. If repeating, then it should
be separated by a new line. Once defined, that variable doesn't need to
appear on the search form, but the default values will be used in search.

Continued on next page

7 Mar 2016 Page 71


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Widgets The Widgets configuration allows you to define custom widgets, as well
as select which of the Default Widgets should be available to users:

To add a custom DQL widget, click Add. Select DQL, enter a Name for
the widget (including selecting from the dropdown from multi-lingual
Display Labels dictionary) and enter the DQL statement (use
${attribute_name} for any attribute value from the selected document):

7 Mar 2016 Page 72


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Add the word VERTICAL at the end of the DQL to display the results in
a vertical list (like the default Properties widget) rather than a horizontal
list.

You can also add the following widgets:


 HTML
 Embedded URL
 Dashboard

Please see the Appendices for some useful widgets you may want to
create.

NOTE ON THUMBNAILS: by default, the thumbnail displayed for a


document is “jpeg_th” with medium_jpeg_th page modifier.

7 Mar 2016 Page 73


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

For the Thumbnail widget:

SMALL THUMBNAIL
 Add rendition where Format = JPEG Thumbnail
 Page Modifier = small_jpeg_th

LARGER THUMBNAIL ON MOUSE-OVER


 Add rendition where Format = JPEG Thumbnail
 Page Modifier = large_jpeg_th

The second tab of the Widgets allows you to define which Widgets
should be visible by default:

Note: in some cases the HTML / URL widgets will not display
anything, as some pages do not display in iFrames. If this is the case,
enter the URL to a JSP page on the application server and in that
page put the desired URL / HTML.

The Widget Settings tab allows definition of the behavior of widgets:

Dashboard widgets should be configured with the Name of the dashboard,


the name of the Report, and the mapping of how the ID of the selected
document would be used in the Dashboard query.

7 Mar 2016 Page 74


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

On the Widgets’ settings tab:

The Max widget height is the height in pixels at which to cap the widget
size, and thereafter build a scrollbar to scroll its contents. This is useful
where widgets might have a lot of information e.g. a long list of Related
Documents.

Hide headers option allows the header rows to be hidden e.g. in the
Properties widget.

There are then two sections to configure the columns for the Version
widget and the Related documents widget. Column management is the

7 Mar 2016 Page 75


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

same as in the Columns section of the View Management, refer to that.

Finally, you can set if the Import Landing Zone will automatically open
the New Document screen on drag and drop or not:

Continued on next page

7 Mar 2016 Page 76


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Settings

The Settings configuration allows you to specify an action to be


performed on double-clicking on a document:
 Show Widget panel: opens the Info panel
 Open document properties: opens the document properties
 Open document properties with preview: opens the document
properties and a preview window side-by-side
 View primary content: opens primary content for viewing
(requires that application installed on the desktop)
 View PDF rendition: opens the PDF rendition for viewing
(requires PDF renditions to exist and Adobe on the desktop)
 Open primary content preview (requires a viewer e.g.
ViewONE Pro or Brava!)
 Open PDF rendition preview with ViewONE Pro: (requires a
viewer e.g. ViewONE Pro or Brava!)
 Edit: checks out the document and opens it for editing.
 View or Edit: asks the user if they would like to View or Edit

Additionally, you can specify where the “Apply Filters” button appears
(to the left or right of filters) and if the filters are applied automatically on
click. Finally, you can determine whether the My WidgetSpace Type
should be based on Tabs or Widget panels (Portal).

Continued on next page

7 Mar 2016 Page 77


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Security The Security configuration allows you to specify which users/groups can
access this View Setting (leaving this blank means all users/groups can
access it).

To make the View applicable to particular users/groups, click the


button to access the list of users / groups – move the desired ones from
left to right using drag & drop / double-click / the arrows and click Save:

Continued on next page

7 Mar 2016 Page 78


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Scripts It is possible to script some behavior for the New Document dialog that
will override the standard inheritance behavior in CARA, when using a
particular view.

Continued on next page

7 Mar 2016 Page 79


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Mobile Nodes This configuration allows you to set the default nodes available when
accessing the CARA Mobile apps.

To add a node, click either Add root node, or select an existing root node
and click Add subnode.

Select the node, and change the label if required. Finally, set which node
should be the default one a user has displayed when entering the app.

Continued on next page

7 Mar 2016 Page 80


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

View Management, Continued

Saving the view When you save the view, the system will prompt you as to whether to
delete all existing users’ personalized views created from this view. You
can either do that (YES) or leave their settings (NO)

Please note that this message has changed around logcal order from
prior versions of CARA.

Saving the view If you have cara_config_manager group membership, then when you
after soft changes make changes to your own display (e.g. showing widgets, changing
column widths etc) you can then choose Save View Settings from the
View menu, and you will also get the message above, as it will reset all
users’ settings who have access to that view.

7 Mar 2016 Page 81


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

`
Direct URL to a document

Direct URL to a CARA allows you to have a direct URL to a document, without going
document through CARA. There are two such URLs one for viewing and one for
exporting.

To create the URL for viewing, you need the following syntax:

http://<server>/<cara-app-
name>/Content/<DocbaseName>/view/<r_object_id>/<a_content_type>/
<page_modifier>/<object_name>

To create the URL for exporting, you need the following syntax:

http://<server>/<cara-app-
name>/Content/<DocbaseName>/export/<r_object_id>/<a_content_type>
/<page_modifier>/<object_name>

Note that this URL can be made available automatically on selecting a


document by creating a custom widget, see the Appendix on Useful
Widget DQLs at the end of this document.

7 Mar 2016 Page 82


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Cabinet Display Label

Changing the To change the display name of cabinets:


display name of 1. Create a no content object of type cara_cabinet_config
the cabinet 2. Save this object in /System/Applications/CARA3/Config
3. Apply the ACL “CARA Configuration” to the object
4. Modify the attributes - set the attribute “display_attr” to the labels
which you would like users to see, e.g.
display_attr
[0]: Generic Name
[1]: Trademark
5. Update the Title attribute on cabinets to have values mapping to
these labels, separated by a semi-colon (“;”)
6. Note that if the title field is blank, the object_name will display.
If the title field contains e.g.
<blank>;value
then the object_name will be displayed when the user chooses to
display (in the example above) Generic name, and will display
“value” when the user selects to display Trademark. The reverse
logic is applied if the title is e.g.
value;<blank>

The user can then change the display label in the Cabinet Restrictions
screen in CARA (see the CARA User Guide for details).

7 Mar 2016 Page 83


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dashboard configuration

About Dashboard Dashboards are a set of screens that display reports, either of information
Configuration from within Documentum, or via a script, external information.

Continued on next page

7 Mar 2016 Page 84


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dashboard configuration, Continued

Adding a 1. From the CARA Start menu, select the Control Panel and click on
dashboard General / Dashboard Management.
2. In the Dashboard configuration screen, click Add:

3. In the Dashboard Properties screen fill in the information as


required:

Continued on next page

7 Mar 2016 Page 85


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dashboard configuration, Continued

Adding a 4. The properties on the General tab are as follows:


dashboard (cont’d)
 Name – Name of the Dashboard (internal)
 Label – the user-facing label used for the Dashboard (select from
the Display Labels dictionary values if required)
 Icon – Icon to be used for the Dashboard display
 Width – Width of the Dashboard (pixels)
 Height – Height of the Dashboard (pixels)
 Display on Desktop – Choose whether the Dashboard will be
displayed on the Desktop (Dashboards will always be available
from the main menus)
 Display in Toolbar – Choose whether the Dashboard will be
displayed on the Toolbar (Dashboards will always be available
from the main menus)
5. Click Save.

Modifying a To modify a dashboard:


Dashboard
properties 1. From the CARA Start menu, select the Control Panel and click on
General / Dashboard Management.
2. In the Dashboard configuration screen, select the dashboard to
modify the properties of, and click Edit.
3. Modify the properties as described above, and click Save.

Deleting a To delete a dashboard:


Dashboard
1. From the CARA Start menu, select the Control Panel and click on
General / Dashboard Management.
2. In the Dashboard configuration screen, select the dashboard to delete
and click Remove.
3. Click Yes to the confirmation:

Continued on next page

7 Mar 2016 Page 86


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dashboard configuration, Continued

Restrictions On the Restrictions tab you can leave the field blank to allow everyone
to access the dashboard, or you can choose some users and groups, in
which case only those users / groups will see the dashboard.

NOTE: these restrictions are to the entire Dashboard – each Report


within a Dashboard also has its own individual restrictions.

Export / Import You can now export and import individual Dashboards (all Dashboards
are exported / imported as part of the overall configuration when done
from the Export / Import tab of the Control Panel.
To export a Dashboard, select it and click Export. Chose a location for
the exported XML file.
To import a Dashboard, click Import and select the Dashboard XML file
on your filesystem to import.

Continued on next page

7 Mar 2016 Page 87


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dashboard configuration, Continued

Populating items To add items to a dashboard:


onto a dashboard
1. From the CARA Start menu, select the Control Panel and click on
General / Dashboard Management.
2. In the Dashboard configuration screen, select the dashboard to work
with, and click Edit.
3. In the screen that appears, go to the Reports tab:

4. Select an existing Report to Edit or Remove (or click the up / down


arrows to reorder) or click Add to create a new Report.
The following pages describe how to define the individual reports.

Continued on next page

7 Mar 2016 Page 88


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dashboard configuration, Continued

Dashboard The General tab allows definition of the basics of the Report:
Reports – General
Tab

The properties on the General tab are as follows:


 Name – Name of the Report (internal)
 Label – the user-facing label used for the Report (select from the
Display Labels dictionary values if required)
 Icon – Icon to be used for the Report display
 Based on – Whether the Report is based on a Query or a Script
 Query / Script – The actual query or script (see Scripts guide for
details on writing a script) for the report
 ID Attribute – the ID attribute to be referenced when executing
actions on the item(s) in the results (see Menu and Toolbar tab
information later on).

Continued on next page

7 Mar 2016 Page 89


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dashboard configuration, Continued

Dashboard It is possible in the Query to define and use variables to allow the user to
Reports – General input some values before executing the Report. To create a query like
Tab – using this, use the following syntax in the WHERE part of the DQL:
VARIABLES
<attribute> <operator> '${string}'
e.g. department_name = '${Department}'
or r_modify_date > ${Date}
NOTE: single quotes around the the ${} only required for string values,
not integer, date, boolean etc.
You can add multiple such variables, for example:
select * from pharma_document where r_modify_date
> ${Date} and discipline like '${Discipline}%'
Repeating attributes are supported with variables, and the IN
DOCUMENT and enable(..), e.g. ENABLE(ROWS_BASED) syntax is
also supported.
Scripts have different ways of using variables, please refer to the scripts
guide for the latest information on those.
It is possible to use [ and ] brackets in the DQL as a conditional part of
the query, but between those brackets only a single variable (${var}) can
be used, e.g.
select * from dm_document where 1=1[ and
r_creation_date>=${date_from}][ and
r_creation_date<=${date_to}]

Dashboard The Columns tab allows you to define the columns to be displayed in the
Reports – Columns Dashboard results. Defining the columns is the same as described on
Tab page 27.
In addition to the Columns definition, on this tab you can also set whether
to Enable paging, and if enabled, what the Page size (number of items
per page) should be.

Continued on next page

7 Mar 2016 Page 90


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dashboard configuration, Continued

Dashboard Dashboards can have variables defined, so that when accessing the
Reports – Dashboard, the user can select certain values for certain fields in order to
Variables Tab generate a report based on desired criteria.
The Variables tab allows you to define both the variables (which should
be used in the query or script defined on the General tab) and the “Form”
(displayed at the top of the Dashboard) where users can make the
variables selection:

To define the variables and form, please refer to the variables and form
definition section in the Custom Actions chapter of this manual on page
339. The steps are identical.
You can also enter a Variables initialization script (e.g. to initialize
values into the variables, based on a selected document if launching the
dashboard as a custom action from a document).

Dashboard The results can have row styles (colors, icons) defined, in the same was as
Reports – Row in the View Management – Row Styles. To set this up for a Dashboard
StylesTab Report, got to the Row styles tab and set the options in the same was as
described on page 30.

Dashboard If the data is chartable (e.g. a count) you can have the Dashboard display
Reports – Charts both a chart as well as the table of data. To enable, this check, the
Tab Enable chart box on the Charts tab.

7 Mar 2016 Page 91


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Then select the attribute to be used as the Chart label column and the
attribute for the Chart value column. Optionally select the chart type
(the user can modify the type in the Dashboard, so this is a default only).
To generate data for charting, use a DQL query with count in it, but
ensure that you alias the count column for better chart display e.g.
select group_name, count(i_all_users_names) as
members from dm_group group by group_name
From CARA v3.7 it is possible to have queries that provide two+ value
columns.

Continued on next page

7 Mar 2016 Page 92


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dashboard configuration, Continued

Dashboard If the results are objects extending dm_sysobject and an ID attribute is


Reports – Menu defined on the General tab, then you can add (right-click) menu and
and Toolbar Tab toolbar items, so that you can click on the results and invoke standard
CARA functions or Custom Actions. To add items to the menu or
toolbar, simply add / remove items on the Menu and Toolbar tab, in the
way described in the View Management (see p44 and p46).
Additionally, there is a dropdown on this tab to define the Double Click
Action that should be available for this Dashboard Report results.

Note on Custom Please note that when calling Custom Actions from a dashboard, you can
Actions - variables now use the variables defined in dashboard to be used in the Custom
Action. For example:
1. Create a dashboard with the following DQL:

select r_object_id, object_name,r_version_label from


dm_document(all) where i_chronicle_id='${parent_id}'
2. Set the ID attribute to r_object_id
3. Define a single Variable named “parent_id” with type ID and
label “Parent ID”
4. Define a form for the variable with just one Label field based on
the parent_id variable
5. Create a new Custom Action with name “Show versions
dashboard” that will open the dashboard defined above
6. Create one variable with name “parent_id” and set the “Source
object property to copy as default value” to “i_chronicle_id”
7. Configure the Restrictions and set the “Required object selection”
to “Single”.
8. Select any document and select “Show versions dashboard” from
the toolbar or menu. A dashboard is displayed with a form. Form
contains one label and it displays the selected document
i_chronicle_id attribute value. Report displays the versions of the
selected document.

Dashboard On the Restrictions tab you can leave the field blank to allow everyone
Reports – to access the dashboard, or you can choose some users and groups, in
Restrictions Tab

7 Mar 2016 Page 93


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

which case only those users / groups will see the dashboard.

7 Mar 2016 Page 94


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

General configuration

General The General Configuration has some items which are too small to go into
Configuration a separate configuration, and are grouped together for ease. From the
CARA Start menu, select the Control Panel and click on General /
General Configuration.

General  New Document Version Label: This determines whether new


Configuration New documents get created at version 0.0, 0.1, or 1.0. Select the
Documents tab appropriate radio button option.
 Enable manual linking and security: Switch on or off the
Documentum folder security, overriding CARA security and
folder rules.
 Checkout and open documents created from templates after
creation: this option will checkout and open documents in the
native application at the end of the document creation process.
 Display warning when not CURRENT version is viewed: this
option will display a warning when a user views a document
where the version label is not CURRENT.
 Display warning when not LATEST version is viewed: this
option will display a warning when a user views a document
where the Latest flag is not true.

Continued on next page

7 Mar 2016 Page 95


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

General configuration, Continued

General
Configuration New
Navigation tab

On the Navigation tab, you can drag and drop the 4 main nodes that
appear in the navigation tree to determine the navigation order of them
(remember, some may not display if they are switched off in the User
Capabilities for example).
You can also specify the Location Change rules, choose whether to
allow or disallow
o Linking
o Copying
o Moving

7 Mar 2016 Page 96


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Relation Type Configuration

What is … Relation type


Documentum allows for documents to be related. CARA extends that
relationship model with the ability to create different categories of
relationship and rules governing the behavior of that relationship.

How to … define 1. From the CARA Start menu, select the Control Panel and click on
relation types General / Relation Types
2. The Relation Types dialog is loaded:

3. In the Relation Type dialog, click Add.


4. In the secondary dialog that appears, enter a name for the Relation
Type (parent to child) and a Converse Name (name of relationship
from child back to parent).
5. Also enter a Label that will appear for the user, from the Display
Labels dictionary. If not label is entered, the relation name is used but
otherwise the Display Labels will allow multi-lingual display:

7 Mar 2016 Page 97


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

6. Select whether the Relation Type should be Active or not.


7. Select the default Icon for the relationship type (this icon replaces the
standard document format icon in the Related Documents widget)
8. Retain relationship across parent versions:
If selected the relationship will not be version specific for the parent
object, it will pertain to all versions of the parent object starting with
the version for which the relationship will originally be created
9. Disable version label field
Disables the Version Label field from being available to end users
10. Disable Retain relationship across parent versions field
Disables the Retain relationship field from being available for end
users to select
11. Disable Comments field
Disables the Comments field from being available to end users
12. On the second tab, select the Security type for the Relation – Child,
Parent or System

7 Mar 2016 Page 98


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

13. Select the type of Referential integrity required for the Relation –
Deletion may be allowed or restricted, or the user may select Cascade
Deletion.
14. Specify either / both the type and category for the parent documents:
if these are empty, no restrictions are applied, and if entered then the
parent documents have to confirm to specific types or categories for
the relationship type to be available
15. Specify either / both the type and category for the child documents: if
these are empty, no restrictions are applied, and if entered then the
parent documents have to confirm to specific types or categories for
the relationship type to be available
16. Specify any Group Restrictions: if empty, the relationship type is
available for all groups / users.
17. Define the Max relations count: the maximum number of relations of
this type allowed on a document
18. Click Save to save the new Relation Type.

Continued on next page

7 Mar 2016 Page 99


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Relation Type Configuration, Continued

How to… modify a 1. In the Relation Type dialog, highlight the relation type to edit and
relation type click Edit.
2. Modify the options as required (and as described in the previous
section on creating a new relation type).

Please note  Once a relation type has been created, the Relation Name cannot be
modified.

How to… delete a 1. In the Relation Type dialog, highlight the relation type to delete
relation type and click Delete.
2. Click Yes to the confirmation:

Please note  The system will warn you if there are existing relations of the type
you are about to delete in the docbase.

7 Mar 2016 Page 100


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Document Format (Icon) Configuration

What is … This is a facility to allow you to define custom icons for particular
document formats.

Content format You can modify / extend the icons used for content formats in CARA.
icon modification You can modify/add to the file icons.js within the CARA web application
(WAR) file using the example below.

var formatIcons = {
bmp: "images/icons/format_bmp.png",
doc: "images/icons/format_doc.png",
docx: "images/icons/format_doc.png",
gif: "images/icons/format_gif.png",
gtc2: "images/icons/format_gtc2.png",
jpeg: "images/icons/format_jpg.png",
jpg: "images/icons/format_jpg.png",
pdf: "images/icons/format_pdf.png",
png: "images/icons/format_png.png",
ppt: "images/icons/format_ppt.png",
tif: "images/icons/format_tif.png",
tiff: "images/icons/format_tif.png",
txt: "images/icons/format_txt.png",
xls: "images/icons/format_xls.png",
xlsx: "images/icons/format_xlsx.png",
xml: "images/icons/format_xml.png",
zip: "images/icons/format_zip.png"
};

Place the modified icon PNG files in the same location in the CARA web
application (WAR) and then reference them in this file. Finally, restart
the application server.

7 Mar 2016 Page 101


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Document Types (Icon) Configuration

What is … Document Types Configuration


This is a facility to allow you to define custom icons for particular
document types.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure General / Document Types Config
Document Type
options 2. The Document Types Configuration dialog is loaded:

3. Click Add to add a rule


4. In the screen that appears, select the Document type from the top
dropdown:

5. Select the Icon to user from the Icon dropdown (the files are
populated from the …\images\icons folder on the web application
server so add custom icons there as required).
6. Click Save.

7 Mar 2016 Page 102


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Folder Types (Icon) Configuration

What is … Folder Types Configuration


This is a facility to allow you to define custom icons for particular folder
types.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Folder General / Folder Types Configuration
Type options
2. The Folder Types Configuration dialog is loaded:

3. Click Add to add a rule


4. In the screen that appears, select the Folder type from the top
dropdown:

7 Mar 2016 Page 103


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

5. Select the Default folder icon to use from the Icon dropdown (the
files are populated from the …\images\icons folder on the web
application server so add custom icons there as required).
6. Select the Not empty folder icon which will be shown when a folder
is not empty.
7. Select whether to Disable document creation in that folder type (the
Linking Configuration will override this setting, so this is for
categories where the Linking Configuration is set to Manual)
8. Select whether to Disable folder creation in that folder type
9. Select whether to Restrict folder types that can be created within
folders of this type (leaving this empty will allow all folder types –
adding items will only allow those items you added to be created
within the selected folder type). To add restrictions, click on the
DOWN arrow to the right of the field and select the folder types from
the secondary list box that appears.

7 Mar 2016 Page 104


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

7 Mar 2016 Page 105


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Sequences Configuration

What is … Sequences Configuration


This is a facility to allow you to define automatic number generation to
apply to documents.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure General / Sequences
Sequences
2. The Sequences Configuration dialog is loaded:

3. Click Add to add a rule


4. In the screen that appears, enter a Name, and choose a Start number
and an Increment.
5. Enter a sequence number format (e.g. 000 or #,##0).
6. Select whether the sequence is to be based on an attribute value,
and if so select the object type and the attribute.
E.g. If you base the sequence on the attribute a_status, then the
sequence number will be different for draft, approved etc.
7. Click Save to save the sequence definition. The sequence can be
referenced in the Auto-values Configuration using the name of the
sequence.

7 Mar 2016 Page 106


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

How to… modify a Select the sequence in the list and click Edit, and follow the steps as
sequence above for creating a sequence definition.

How to… remove a Select the sequence in the list and click Remove.
sequence

How to… show Select the sequence in the list and click Show Running. A screen will
running sequences appear showing the sequence information:

Select the running sequence and click Remove to reset the sequence.

7 Mar 2016 Page 107


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Staging Area

What is … Staging Area


The staging area is an area within the docbase to which documents can be
uploaded easily, without much metadata, allowing the same / users to
return to those documents at a later point to either fully classify them (and
thus have them moved to the “main” docbase cabinets) or reject them.

Documents can be added to the Staging Area using:


- Drag and Drop
- Sending as email attachments to a particular email account
- Uploading from mobile devices using the CARA App

Documents in the staging area have limited metadata:


- Name
- Description
- Owner Name
- Creation Date

Open the Staging On the General tab of the Control Panel, click on the Staging Area. First
Area Configuration of all, decide if you want emails or just their attachments to be uploaded:

Continued on next page

7 Mar 2016 Page 108


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Staging Area, Continued

ACL Mapping By default, if left blank, the staging area uploads content from existing
docbase users and applies a private ACL so that only those users can see
the objects, and later re-classify them. In order to allow for different
security models, you can add configurations so that documents loaded by
users or members of groups have different ACLs applied (e.g. so multiple
people can re-classify). Note that you can use this together with the email
mapping below, so that for example a third party (non docbase user) who
emails content will have it uploaded with a particular group in CARA
having access to classify the documents.

To add a mapping:
1. Click Add
2. In the popup, select the user/group and the ACL to which to map
it, and click Save:

Continued on next page

7 Mar 2016 Page 109


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Staging Area, Continued

Email Mappings By default, if left blank, users who email content to the watched docbase
account will have their email address reconciled with their docbase email
details, and own the content. Anything which cannot be reconciled will
be mapped to dmadmin.

Select whether the mapping will be based on the email address of the
Sender or Recipient. To change the mappings (e.g. to have specific email
domains mapped to particular docbase users to own) set up a specific
mapping:

To add a mapping:
1. Click Add
2. Enter the email pattern (using RegEx format) and select the target
user name.

Mail configuration To have emails automatically ingested, you must set up the appropriate
Mail Configuration – refer to the chapter on that in this guide.

7 Mar 2016 Page 110


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Scripts Library

What is … The Scripts Library allows you to write and save scripts which you can
then call from all other scripting points in CARA – enabling efficient re-
use of code.

Using the Scripts On the General tab click on the Scripts Library button:
Library

Click Add to add a script – simply give the script a name and write in the
script. Note that scripts can also be exported and imported.

Continued on next page

7 Mar 2016 Page 111


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Scripts Library, Continued

Using scripts from To use a script, simply have a function in the script library script that you
the library can call e.g.:

Then in your script call that function e.g.:

7 Mar 2016 Page 112


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

LifeCycle
Lifecycle Configuration

What is … Lifecycle Configuration


CARA allows you to configure many of the common lifecycle actions
within the application, giving you a greater degree of control than setting
them at the Lifecycle level using Composer for example.

Open the Lifecycle On the Lifecycle tab you will find all the installed lifecycles listed for
Configuration configuration. Click on the desired lifecycle to open it for editing:

Configuring a state On the States tab, you will see each state of the lifecycle listed. Click on
a state and click the Configure button to access the configurations:

Continued on next page

7 Mar 2016 Page 113


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Lifecycle Configuration, Continued

Configuring a state For each state that you configure, you can specify whether or not it is
(cont’d) Attachable. Note that only those states defined as attachable in the
lifecycle itself can be set attachable in CARA; however, if a state is set
attachable in the lifecycle you can make it non-attachable in CARA:

On the Actions tab, you can then click to add actions:

Simply select the action type from the dropdown and select (optionally)
any categories to which the action applies (selecting nothing will have the
action applied across all categories).

Continued on next page

7 Mar 2016 Page 114


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Lifecycle Configuration, Continued

Configuring a state The actions are:


(cont’d)

If you select to execute a script, you enter the script into the Script field.
Note that the script is a JavaScript-style script to be executed on status
change where 'object' variable is a Documentum object and can be used to
modify object properties. E.g. 'object.setString("owner_name",
session.getUser(null).getUserName());'. DFC classes as well as Java
classes can be used. Documentum session is available as 'session'
variable.

Additionally, you can use standard CARA operations e.g. change state or
delete. Here is an example script which will start a Task from a template
called “Author” on state change:

var op =
operationFactory.getOperation(com.generiscorp.cara.dctm.api.operations.workflow.Prepa
reNewWorkflowDefinitionOperation, sessionContext, repository);
op.setWorkflowTemplateId(session.getIdByQualification("cara_workflow_template where
object_name='Author'").getId());
op.add(object.getObjectId().getId());
op.execute();

var workflow = op.getResult();


workflow.setCreator(userName);

var opSave =
operationFactory.getOperation(com.generiscorp.cara.dctm.api.operations.workflow.Save
WorkflowOperation, sessionContext, repository);
opSave.setWorkflow(workflow);
opSave.add(object.getObjectId().getId());
opSave.execute();

var issueOp =
operationFactory.getOperation(com.generiscorp.cara.dctm.api.operations.workflow.Issue
WorkflowOperation, sessionContext, repository);
issueOp.add(opSave.getCreatedWorkflowsIds().get(0));
issueOp.execute();

7 Mar 2016 Page 115


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Continued on next page

7 Mar 2016 Page 116


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Lifecycle Configuration, Continued

Configuring a state If you select to delete previous versions of a particular status, select the
(cont’d) status to delete.

If you select to promote previous versions of the same status to another


status, select the status to promote them to (this cannot be a suspension
state)

You can also select to change to the next major version

Continued on next page

7 Mar 2016 Page 117


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Lifecycle Configuration, Continued

Configuring a state You can select multiple actions to be performed:


(cont’d)

On the Notifications tab you can set the users or groups to notify on a
document getting to the particular state.

First of all, enter the name of the email template to be sent:

Continued on next page

7 Mar 2016 Page 118


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Lifecycle Configuration, Continued

Configuring a state Next, select the users or groups to notify, including using dynamic users
(cont’d) or groups where the name will be constructed from a document attribute
e.g. <department>_managers:

Configuring The Transitions tab allows you to configure which transitions are allowed
transitions (and these are allowed in CARA from any state to any other state which is
attachable, so unlike standard Documentum it does not require a step-
wise progression through the states):

Continued on next page

7 Mar 2016 Page 119


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Lifecycle Configuration, Continued

Configuring When you first open a lifecycle to configure, all the states have
transitions (cont’d) Transitions defined based on those available in the Lifecycle itself (e.g.
state 1 to state 2, state 2 to state 1).

To modify an existing transition, select it and click Edit, or to create a


new one click Add. On the General tab for the transition, you can set a
label for the transition which is what will appear for the end user in the
Status Manager:

Choose the restrictions:


 Allow manual transition (the transition appears in the Status
manager or only be available for back end processes such as tasks)
 Validate mandatory properties – mandatory properties will be
validated as not being empty before the transition is allowed
 PDF rendition is required – the transition will not be allowed if a
PDF rendition is not present
 Users / groups - User/group name or a calculated value, e.g.
<department>_users. Leave empty to allow all.
 Category restrictions – select whether to restrict this transition to
certain categories or leave it open for all categories

Continued on next page

7 Mar 2016 Page 120


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Lifecycle Configuration, Continued

Configuring On the Conditions tab, you can define additional conditions for when the
transitions (cont’d) transition is allowed:

If the transition should only be allowed in certain circumstances, check


the Enable document based conditions box. Choose whether, when the
conditions are met, to Disable or Enable the transition – select from
All¸Any, or Custom (allows you to select multiple criteria and decide the
AND / OR between them)

Then click Add to add a condition

Continued on next page

7 Mar 2016 Page 121


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Lifecycle Configuration, Continued

Configuring
transitions (cont’d)

If selecting a folder path, click Next and enter the values:

If selecting Document property, select the property from the dropdown


and click Next. In the next screen, enter the conditional values (the
options will depend on the property type) and click Save

If selecting a User Name or Group Name, click Next. Enter the


user/group condition and click Save:

Continued on next page

7 Mar 2016 Page 122


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Lifecycle Configuration, Continued

Configuring
transitions (cont’d)

If selecting a User Name or Group Name, click Next. Enter the


user/group condition and click Save:

Add other conditions (evaluated on AND basis).Add other conditions


(evaluated on AND basis).

Finally, enter (optionally) a Custom validation message to present to the


user when the conditions are not met.

7 Mar 2016 Page 123


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dictionary Manager
Opening a dictionary

What is … A dictionary is a list of data values together with abbreviations and aliases

How to … open 1. From the CARA Start menu, select the Control Panel and click on
Dictionaries Data / Dictionaries.
2. The Dictionary Manager is loaded listing all existing dictionaries.

NOTE: System dictionaries that are required by CARA are shown in Red
and cannot be deleted. You can modify values in those dictionaries,
however. You can filter the view to only show System or Non-system
dictionaries using the radio button options at the top.

Continued on next page

7 Mar 2016 Page 124


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Creating a New Dictionary

How to … create a 1. Within the Dictionary Manager click New


new dictionary
2. In the dialog that appears, provide a Name for the dictionary to be
created, and the maximum length for each dictionary entry (32 in the
screenshot below):

3. Optionally select to specify an abbreviation and the length for that


abbreviation (default is 4, and the maximum cannot be greater than

7 Mar 2016 Page 125


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

the value for the length of the dictionary entry).


4. Disabling the automatic value sorting will allow you to define the sort
order manually for the items (e.g. so items “High” “Medium” “Low”
are sorted in that order).
5. Optionally Aliases can be added to the dictionary by selecting the
Add button. An alias is a different display value for a particular
dictionary value e.g. dictionary for Products could have an alias of
“Name in the USA” and “Name in Europe”:

Or there can be aliases for languages using language codes e.g. en, fr):

The alias name may exceed the dictionary entry length defined. To
remove an alias, select the alias and click Remove. To modify an
alias, double click on the cell/row to be modified, make the changes,
and click Save.
6. Optionally, add some groups which should have access to update the
values in the dictionary (they will not be allowed to create or delete
dictionaries)
7. Choose OK to save the entered dictionary properties dialog to
completion creation of the new dictionary.
NOTE: it is not advised to change an alias name once some values have
been added to the dictionary.

Continued on next page

7 Mar 2016 Page 126


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Creating a New Dictionary, Continued

Special case The following dictionaries are special case dictionaries, which can be
dictionaries created to achieve certain functionality:
1. Name: Display Labels
Length: 255 characters
Aliases Named after language code e.g. “en”, “fr”, “de”
Any length
Entry: Put a default value in the entry
Alias value: Put desired display label default value in the
selected language
Functionality In CARA Web, if users select a different language
other than English for display of the application,
then if this dictionary exists AND an alias exists
that matches the language selected, AND
properties or search configurations are set up
accordingly then the label will be displayed
translated. Otherwise if there is no entry for the
label folder OR no alias matching the language, the
default value will be displayed

2. DocSecure dictionaries: these are provided to support DocSecure


configuration through CARA. They should not be adjusted.

Continued on next page

7 Mar 2016 Page 127


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Creating a New Dictionary, Continued

Special case
dictionaries
3. Name: New Document Labels
(cont’d) Length: 124 characters
Aliases Named after language code e.g. “en”, “fr”, “de”
Any length
Entry: Put a default value in the entry
Alias value: Put desired display label default value in the
selected language
Functionality In the New Document screen, the various options
can have translated labels (since these are often
required to be company-specific.

Special case
dictionaries
4. Name: Audit Events
(cont’d) Used to hold display labels for audit events for the audit trail
5. Name: E-sig Events
Used to hold information on events where a DocSecure rendition
should be removed.

7 Mar 2016 Page 128


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Modifying a Dictionary

How to … Modify 1. Open the Dictionaries Manager configuration


the properties a
dictionary 2. Choose an existing dictionary from the list in the dialog and click
Properties.
3. The current settings for the dictionary are displayed and can be
modified as desired in the same way as setting the original dictionary
properties described in the previous section.

7 Mar 2016 Page 129


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Working with Dictionary values

How to … work 1. Within the Dictionary Manager choose an existing dictionary from
with dictionary the list and select Open or double click the desired dictionary.
values
2. The dictionary’s content is displayed in the Dictionary Listing dialog.

3. For each dictionary entry (represented by a row in the Dictionary


Listing) the following functions are available:
 Add – to add a new value and associated aliases click Add, and
complete the information in that row, then click Save:

 Edit – double-click in a row, edit the information in that row,


then click Save
 Remove – highlight the row (do NOT use the checkbox) and
click Remove.
 Set Active / Inactive – use the checkbox.
4. Once changes have been made to the content of the dictionary the can
be permanently saved using the Save button or discarded using the
Cancel button.

Continued on next page

7 Mar 2016 Page 130


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Working with Dictionary values, Continued

Populating To populate your dictionary with values which are the result of a DQL
dictionaries from statement
DQL
1. Click on the Populate with DQL button:

2. Enter the DQL, and specify whether the results should replace
existing data (otherwise they will be appended), and click Import.

7 Mar 2016 Page 131


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Importing and exporting a dictionary

Exporting a To export a dictionary as an XML file, select it in the main Dictionary


dictionary as an Manager screen, and select Export. Select the location where you wish
XML file to place the exported file and click OK.

Importing a A dictionary that has been set up as an XML file can be imported (e.g.
dictionary from an one previously exported). Simply click Import from the main Dictionary
XML file Manager screen, select the XML file, and click Import. The dictionary is
created as defined in the XML.

Exporting Dictionary values can be exported to Excel from inside the dictionary
dictionary values screen. Open the dictionary from the main Dictionary Manager screen,
to Excel and Export to Excel.

Importing To upload new dictionary values from an Excel sheet, the easiest route is
dictionary values to first export one to Excel, then clear the values in order to have the right
from Excel columns available. Enter new data, and then in the Dictionary Manager,
open a dictionary to edit, and click Import. Browse to the Excel file (.xls
only, not .xlsx) and select whether to Replace the existing data or not:

7 Mar 2016 Page 132


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Deleting a Dictionary

How to … delete a 1. Within the Dictionary Manager screen choose an existing dictionary
dictionary from the list to permanently remove and select Delete
2. A confirmation dialog is displayed, asking if you want to delete the
dictionary completely (in which case it will be marked as hidden) or
just remove the current version, thus leaving the last one effective:

Please note When deleting a dictionary which is referenced in a taxonomy the


taxonomy will remain valid with the values of the former dictionary
which have been added to the taxonomy still available. Values of the
former dictionary which have not yet been added to the taxonomy will
although not be available for adding after the dictionary has been deleted.

7 Mar 2016 Page 133


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

CARA Default Dictionaries

CARA default The following dictionaries are default CARA product dictionaries, and
dictionaries – Do must not be deleted:
Not Delete
Dictionary Purpose
Audit Events List of events which can be audited.
If you register a new event in
Documentum, add it to this
dictionary so it becomes available
to the CARA Audit Configuration.
Display Labels Holds values that are used in
properties screens, search screens
etc, and multi-lingual aliases. This
dictionary can be added to or have
values modified.
New Document Labels Holds the values and multi-lingual
aliases for the options presented to
the user in the New Document and
New Structure screens.

Display Labels The node labels can be modified in CARA (e.g. “Dimension”). These are
dictionary – managed in the Display Labels dictionary. If the values below do NOT
special case for exist, the application default labels will be used. If they DO exist, the
Node Labels language alias will be used where available, otherwise the default
language (or EN) label will be used.

Dictionary core value Node which is affected

NODE_CABINETS Cabinets node

NODE_MY_DESK My Desk node

NODE_HOME Home cabinet node

NODE_FAVORITES Favorites node

NODE_SUBSCRIPTIONS Change Notifications node

7 Mar 2016 Page 134


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dictionary core value Node which is affected

NODE_RECENT_ITEMS Recent items node

NODE_CHECKED_OUT Checked out items node

NODE_SEARCH_RESULTS Search results node

NODE_SEARCHES Saved Searches node

NODE_DCTM_INBOX Documentum Inbox node

NODE_DCTM_INBOX_TASKS Documentum Inbox / Tasks node

NODE_DCTM_INBOX_NOTIFICATIONS Documentum Inbox / notifications node

NODE_WQ Documentum Work Queue node

NODE_TASKS CARA Tasks node

NODE_TASKS_IN_TRAY CARA Tasks / Intray node

NODE_TASKS_CREATED_BY_ME CARA Tasks / Created by me node

NODE_TASKS_OUT_TRAY CARA Tasks / Outtray node

NODE_TASKS_READY_TO_ISSUE CARA Tasks / Ready to issue node

NODE_DIMENSIONS Dimensions node

NODE_SLN SnapLists node

Display Labels To customize a menu or toolbar label just add an entry to Display Labels
dictionary – dictionary starting with MENU_ for menu items or TOOLBAR_ for
special case for toolbar button labels. The list of available actions to customize is listed
menus and below:
toolbars
PROPERTIES
PERMISSIONS
PROPERTIES_DUMP
VIEW
DOWNLOAD

7 Mar 2016 Page 135


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

EDIT
CHECKOUT
CHECKIN
CANCEL_CHECKOUT
EXTRACT_EMAIL_ATTACHMENTS
EXPORT
DEEP_EXPORT
SEND_AS_URL
SEND_TO
SEND_AS_EMAIL_ATTACHMENT
ADD_TO_FAVORITES
ADD_TO_OTHERS_FAVORITES
REMOVE_FROM_FAVORITES
NEW_DOCUMENT
NEW_STRUCTURE
NEW_FOLDER
NEW_CABINET
NEW_DOCUMENT_TEMPLATE
NEW_STRUCTURE_TEMPLATE
BATCH_IMPORT
DUPLICATE
PROPERTIES_WITH_PREVIEW
PREVIEW
VIEW_PDF
PREVIEW_PDF
VIEW_IN_TABS
PRINT
CONTROLLED_PRINT
ADD_RENDITION
REQUEST_PDF_RENDITION
ADD_RELATIONSHIP
IMPORT_ANNOTATIONS
RELATIONSHIP_MANAGER
ANNOTATION_REPORT
DELETE_OBJECT
DELETE_SECTION
DELETE_NOTIFICATION
VD_MANAGER
CONVERT_VD_TO_STRUCTURE
VD_VIEW_SNAPSHOTS
FREEZE
UNFREEZE
ADD_TASK
ISSUE_TASK
START_TASK
COMPLETE_TASK

7 Mar 2016 Page 136


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

DELEGATE_TASK
REMOVE_TASK_FROM_OUTTRAY
TASK_MANAGER
TASK_REPORT
TASK_TEMPLATE_MANAGER
DCTM_WORKFLOW_START
DCTM_WORKFLOW_REPORTING
ADVANCED_SEARCH
SEARCH_TRASH
AUDIT_TRAIL_REPORT
DASHBOARDS
PUBLISHING_LOCK
STATUS_MANAGER
API
DQL
SCRIPT
CABINET_RESTRICTIONS
CHANGE_CHECKOUT_LOCATION
DISTRIBUTION_LISTS
OPEN_CHECKOUT_LOCATION
OUT_OF_OFFICE_SETTINGS
RESET_VIEW_SETTINGS
COPY_HERE
COPY_MOVE_NODE_HERE
COPY_TO_CLIPBOARD
COPY_URL
INSERT_DOCUMENTS_HERE
LINK_HERE
MOVE_HERE
PASTE_WORKFLOW_HERE
SUBSCRIBE
UNSUBSCRIBE

7 Mar 2016 Page 137


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Taxonomy Manager
Opening a taxonomy

What is … A Taxonomy is a hierarchy of data values from multiple dictionaries.

How to … open 1. From the CARA Start menu, select the Control Panel and click on
Taxonomies Data / Taxonomies.
2. The Taxonomy Manager is loaded listing all existing dictionaries.

3. The following functions are available:


 New
 Properties
 Import
 Export
 Open
 Delete

7 Mar 2016 Page 138


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Creating a New Taxonomy

How to … create a 1. Within the Taxonomy Manager choose New


taxonomy

2. Provide a Name for the taxonomy to be created


3. Select Dictionaries for Levels 1 through 9 as appropriate.
4. Click Save.

7 Mar 2016 Page 139


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Working with a Taxonomy

How to … modify 1. Within the Taxonomy Manager choose an existing taxonomy from the
an existing list and select Properties
taxonomy
properties 2. The current settings for the taxonomy are displayed and can be
modified as desired analog to the taxonomy creation.

How to… modify 1. Within the Taxonomy Manager choose an existing taxonomy from the
taxonomy entries list and select Open.

2. To add an item at a particular level, select anything on that level, and


click Add Item.

Continued on next page

7 Mar 2016 Page 140


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Working with a Taxonomy, Continued

How to… modify 3. In the screen that appears, select the dictionary entry/entries you wish
taxonomy entries to add and click Add Items (or use the Select all or Deselect all):
(cont’d)

4. To add an item at a sub-level level, select anything on that level, and


click Add Sub-item. Repeat the process in the previous step.
5. To set an item inactive, click Set Inactive – this means the item will
not appear in any drop-downs but will be maintained on any
documents and search results.

6. To remove an item, select it and click Remove. Removed items will


no longer be available in the search.

7 Mar 2016 Page 141


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Importing and exporting a taxonomy

Importing a A taxonomy that has been set up as an XML file can be imported. Simply
taxonomy from an click Import from the main Taxonomy Manager screen, select the XML
XML file file, and click Import. The taxonomy is created as defined in the XML.

Importing a A taxonomy can be set up in an Excel file as in the example below, and
taxonomy from an this will then be imported as a taxonomy tree.
Excel file
<Dictionary 1> <Dictionary 2> <Dictionary 3>
Test Script Regression
Test Script System
Test Log Output
Result Report Output

To import from Excel, first OPEN the taxonomy in question, and then use
the import button there.
NOTE: This works for .xls format only. Also, importing from Excel into
the taxonomy that is used as the docbase Classification WILL overwrite
all existing Classification-based configurations, so use with caution.

Exporting a To export a taxonomy as an XML file, select it in the main Taxonomy


taxonomy Manager screen, and select Export. Select the location where you wish
to place the exported file and click OK.

7 Mar 2016 Page 142


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Deleting a Taxonomy

How to … delete a 1. Within the Taxonomy Manager screen choose an existing taxonomy
taxonomy from the list to permanently remove and select Delete
2. A confirmation dialog is displayed, click Yes.

3. You will then be asked whether you want to completely delete the
taxonomy (in which case it will be marked as hidden) or just delete
the latest version, leaving the prior one as the latest:

7 Mar 2016 Page 143


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Registered Tables
Modifying registered table data

What is registered A registered table is a database table which is registered (dm_registered


table? object) in Documentum, often used to provide data for picklists. CARA
allows admin users to add / modify / delete data from a registered table
without needing to go through SQL at the database level.

How to … add data 1. Open the Control Panel and go to the Data tab. Click on the
to a registered Registered Table icon:
table

2. Select the registered table to modify and click Edit:


3. Click the Add button, enter the value(s) and click Save:

7 Mar 2016 Page 144


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

4. Alternatively, you can Import from Excel, and also Export values to
Excel (to facilitate migration from one docbase to another).
5. Click Close.

How to … edit data 1. Open the Control Panel and go to the Data tab. Click on the
in a registered Registered Table icon, select the table to edit and click Edit.
table
2. Select the value to edit, and click Edit. Edit the value and click Save.

Continued on next page

7 Mar 2016 Page 145


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Modifying registered table data, Continued

How to … delete 1. Open the Control Panel and go to the Data tab. Click on the
data from a Registered Table icon, select the table to edit and click Edit.
registered table
2. Select the value to delete, and click Delete.

7 Mar 2016 Page 146


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Classification Configuration
Classification Definition

What is a A classification is a particular value in the taxonomy tree and documents


classification? are all mapped to a particular classification. For each classification, a
particular set of rules can be applied. One taxonomy is selected to be the
Defining Taxonomy of the docbase.

How to … set 1. From the CARA Start menu, select the Control Panel and click on
classification Classification / Definition

2. Select the desired Defining Taxonomy from the list of available


taxonomies. The values of the taxonomy will be displayed in the left
hand pane of the dialog.
3. Select the Base Object Type from the list of available object types.
Only objects of this type including any sub type can be created then.

Continued on next page

7 Mar 2016 Page 147


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Classification Definition, Continued

How to … set 4. Specify the Property Mappings for each level (the number of levels
classification will appear automatically based on the number of levels in the
(cont’d) selected Taxonomy) by selecting the values from the individual list
boxes. This setting defines in which Documentum property the
values will be stored when creating and manipulation objects and
their properties in.
5. Specify the labels for the New Document screen.
6. For each option in the New Document Configuration section, select
 Whether the option should be available or not
 How many levels of the classification are mandatory when
using that option to create document / structure instances
 How many levels of the classification are mandatory when
using that option to create document / structure templates

Copying Once you have defined a classification for a particular node in the tree
configurations to (see all the following sections), you can right-click on the node and Copy
other classification the configuration, and then single or multiple select (using shift or Ctrl)
nodes other nodes and apply the configuration – this copies the configuration
and “pastes” it to the other nodes, overwriting what was on there before
(including switching off the “inherit” option where necessary).

Continued on next page

7 Mar 2016 Page 148


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Classification Definition, Continued

Classifications In some cases the dictionary might have aliases defined (language or
where the other, e.g. store and integer and display a value). In this case the
Dictionaries have Classification configurations will display the stored value and the “en”
aliases alias if one exists, in brackets, e.g.
1 (Value1)
1.1 (Subvalue1)

7 Mar 2016 Page 149


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Classification Restriction

What is a You may not want certain users to be able to select certain items in the
classification classification tree when creating documents and/or structures – the
restriction? restrictions configuration allows you to set up those rules.

How to … set 1. From the CARA Start menu, select the Control Panel and click on
classification Classification / Restrictions
restrictions

2. Select the desired classification item on the left. To set specific


rules, uncheck the option Settings cascade from parent
classification.
3. Set the restrictions as follows:
 To make the item unavailable to all users and groups for
document creation, check that item.
 To make the item unavailable to all users and groups for
structure creation, check that item.
 To allow creation of documents of that classification
ONLY in particular folder types, check that option. Then
click on the DOWN arrow at the side of the field and

7 Mar 2016 Page 150


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

choose the relevant folder types, then click Save:

4. To enable / disable the item for a particular user/group, (for


creating an object) click on the DOWN arrow to the side of that
field, and in the new screen that appears, select the user(s)/group(s)
from the left and move them to the right, and click Save:

5. Select whether you are enabling it (“Available only for the


selected users/groups”) or disabling it (“Available for other
users/groups”):

7 Mar 2016 Page 151


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

6. Repeat for the “User/Group search restrictions” - this would


enable or disable that item being available for searching on for
particular users or groups.
7. Click Save after making all required changes.

7 Mar 2016 Page 152


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Type, Lifecycle and Template Configuration

What is … type, Type: This allows you to set the object type to be set for documents for
lifecycle and any particular point in the Classification tree.
template
configuration Lifecycle: This allows you to set the lifecycle to be applied for the
particular object type at the selected point in the Classification tree.

Properties configuration(s): This allows selection of the properties


configuration(s) to be used for the selected point in the Classification tree.

Template(s): This allows selection of the Template(s) to be available for


the selected point in the Classification tree.

How to … set type, 1. From the CARA Start menu, select the Control Panel and click on
lifecycle and Classification / Type, Lifecycle, Templates
template
configuration 2. The Type and Lifecycle Assignment screen is loaded:
For every element of the classification (root or child element), which is
displayed in the left hand part of the dialog, configure:
 Cascade from parent (not applicable for root elements):
Settings will be inherited/cascaded from parent
 Object Type: All subtypes of the Classification’s Base Object
Type and the Base Object Type itself are available.
This setting determines the object type of new objects as they are
being created based on the classification selected by the user.
 Lifecycle for documents: This setting determines the lifecycle
being applied to an object during the object’s creation process.
 Lifecycle for Templates: This setting determines the lifecycle
being applied to a template object during the object’s creation
process.
 Property Configuration(s): Allows the assignment of specific
property dialog(s) on a Classification level.
 Template(s): Allows the assignment of specific template(s) to a
Classification level. OR
 Select all templates available: Will pull all available templates
with the right classification, so that the user does not have to go
and manually select every single classification-relevant template.

Continued on next page

7 Mar 2016 Page 153


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Type, Lifecycle and Template Configuration, Continued

How to … set type


and lifecycle
configuration
(cont’d)

3. Select the point within the Classification hierarchy which groups all
elements with the same object type and lifecycle configuration
underneath it and select object type, lifecycle, properties and
templates in the right hand section of the dialog accordingly.

4. Go to the Templates tab to control Templates.


5. If preferred, instead of selecting individual templates that should be
applicable, select the option “All templates available” which will
make all templates with that particular Classification OR object type
available.
6. You can also choose to define a DQL condition for which Templates
are available.
7. Finally, you can choose to have the Template Name saved to a
particular attribute of any document created using the template.

7 Mar 2016 Page 154


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

8. Select Save. Repeat for other elements of the Classification as


needed.

Please note  CARA facilitates the Documentum Lifecycle model. The lifecycle is
defined and configured using the Documentum tools for building
lifecycles. The Lifecycle has to be set up for the appropriate object
type(s).
 Using multiple Properties Configurations for a single classification is
supported for backwards compatibility. With the latest version of
CARA where individual fields / tabs can be shown or hidden based on
rules, we recommend managing everything except the split of
New/Import and View/Edit in a single properties configuration.

7 Mar 2016 Page 155


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Mandatory Properties Configuration

What is … Mandatory Property:


Mandatory Property that has to be completed before the object may be saved.
Properties Template:
Configuration Model documents, stored in a specific location within the docbase
(/Templates)

How to … set 1. From the CARA Start menu, select the Control Panel and click on
Mandatory Classification / Mandatory Properties
Properties
Configuration 2. The Mandatory Properties dialog is loaded:

For every element of the classification (root or child element), which is


displayed in the left hand part of the dialog, the following settings are
configurable:
 Settings cascade from parent: Settings will be
inherited/cascaded from parent
 General: mandatory properties selection for document instances
 Template: mandatory properties selection for templates

Continued on next page

7 Mar 2016 Page 156


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Mandatory Properties Configuration, Continued

How to … set 3. Select the point within the Classification hierarchy at which to define
Mandatory mandatory properties. To add one or more properties the General or
Properties Template tab and open the Select Properties dialog by clicking in
Configuration
the right hand part of the dialog.
(cont’d)

4. Add /remove property(ies) to / from the list using the arrow buttons or
double click and select OK.
5. The selected properties are listed in the Mandatory Properties dialog
6. Select Save
7. Repeat above steps for other elements of the Classification as
required, and finally click Save to close the dialog.

Continued on next page

7 Mar 2016 Page 157


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Mandatory Properties Configuration, Continued

Precedence of Properties are typically defined as mandatory or not for a particular type
setting mandatory in Documentum at the type Data Dictionary level or the aspect level.
properties
CARA allows you to set the mandatory switch in other, more flexible
places, and we therefore do not recommend setting any properties to
mandatory at the type or aspect level.

The places where the mandatory setting can be made, and the sequence in
which they are read, is as follows:

Setting Description
Documentum type definition On or off for all objects all users –
no flexibility
CARA Mandatory Properties For a single type switch on or off
configuration based on Classification values
CARA Properties configuration, for For a single type switch on or off
each control, on the first tab based on Classification values,
AND switch on or off depending
on user/group (since you can have
different properties configurations
per user/group)
CARA Properties configuration, for For a single type switch on or off
each control, on the Mandatority based on Classification values,
tab (conditional) AND switch on or off depending
on user/group (since you can have
different properties configurations
per user/group) AND switch on or
off depending on values of other
properties

7 Mar 2016 Page 158


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Properties Initialization Configuration

IMPORTANT Do not reference any attributes used in the Classification levels in the
Properties initialization as it will overwrite the Classification.

How to … set 1. From the CARA Start menu, select the Control Panel and click on
properties to be Classification / Property Initialization
initialized
2. The Property Initialization dialog is loaded:

3. Select the point within the Classification hierarchy at which to set


property initialization and select:
 Settings cascade from parent classification (not applicable for root
elements):
Settings will be inherited/cascaded from parent
 Identifiers: Select none, one or multiple properties which should
be set respectively prefixed according to the following settings:
 New Document:
Is Named: Enter the default name (e.g. Untitled)
 Copy of Existing Document:
Is Named: Enter the default name (e.g. is copy of) or
Is Prefixed: Enter the prefix to be assigned
 New Document from Model/Template:
Is Named: Enter the default name (e.g. New) or

7 Mar 2016 Page 159


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Is Prefixed: Enter the prefix to be assigned


IMPORTANT NOTE: when modifying the properties of
multiple documents, any properties listed in the
Identifiers tab of the Property Initialization will not be
available for the user to edit.
 Inherited property values:
Select none, one or multiple properties (from the Properties
Selection dialog – open via ) which shall be inherited from
adjacent documents in a structure (CARA only) or adjacent
documents in the folder.

NOTE: If you select a particular document before starting the


New Document creation process, it will inherit the properties
from that document.

 Cleared property values:


Select none, one or multiple properties which shall always be
cleared (reset, initialized) for user input.
 Settings: This will be a list of properties that are set as default to
a particular value. To add a default, click Add and then select the
property and enter a value. Note that you can use a comma , as a
delimiter for repeating properties, T/F for Boolean values and the
keywords “Now” and “Today” for date values, and the keyword
“User” to get the user name.

7 Mar 2016 Page 160


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Click Add to add a new rule, and complete the information as shown
below. Alternatively, select an existing rule and click Edit to edit, or
Remove to remove.

 User specific preset property values: Select none, one or multiple


properties which are user dependent and shall take initial values
from other documents in the same folder or part of the structure
dependent on the document creator.
 Structures: this will populate properties from a structure root
onto components when adding them into a structure. NOTE: this
inheritance is done on saving a document or adding it to a
structure, not on opening the properties screen, unlike the others.
 Folder: this will populate properties from those on the selected
folder itself – select the folder property to inherit to the document:

 Cabinet: this will populate properties from those on the cabinet in


which the document is being created - select the cabinet property
to inherit to the document in the same way as above.
4. Select Save to save the settings. Repeat above steps for other elements
of the Classification. At the end click Close to close the dialog.

7 Mar 2016 Page 161


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Auto-values Configuration

What is … Auto-values:
This configuration allows you to set property values automatically based
on certain rules, including sequences.

How to … set 1. From the CARA Start menu, select the Control Panel and click on
Auto-values Classification / Auto-values Configuration
2. The Automatically Generated Values dialog is loaded:

3. Select the point within the Classification hierarchy at which to set


property initialization and select:
 Settings cascade from parent classification (not applicable for root
elements):
Settings will be inherited/cascaded from parent
4. Click Add to add a rule.

Continued on next page

7 Mar 2016 Page 162


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Auto-values Configuration, Continued

How to … set 5. In the screen that appears, select which attribute the rule applies to:
Auto-values
(cont’d)

6. Enter a value to be applied to the property in the case that the token
cannot be resolved.
7. Enter the rule as described in the text below the rule box. NOTE:
there should be no spaces inside a tag.
8. Click Save. In the main Auto-values screen, enter other rules for that
classification level or Edit or Remove existing rules, or create /
modify / remove rules for other classification levels, always clicking
Save to save them. Click Close to close the Auto-values screen.
NOTE: if you are using a date field in the Auto-values, you can optionally
define a format like this:

7 Mar 2016 Page 163


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

<document_date,MM-dd-yyyy>
An example of the IIF syntax is given below:
<doc_number,sequence(Num)>-<department,abbrev(Department)>
<IIF({<add_name>}{<>}{},{ (<add_name>)},{})>
e.g. <IIF({department_name}{<>}{Development},{Yes},{No})>

How to … set Another example:


Auto-values
(cont’d)
The following syntax checks whether "free_text" appears in the value
before calculation - before the "<free_text>" is replaced with a real value
in that string

<IIF({<full_title>}{~~}{free_text},{},{ <free_text>})>

The syntax below does the same but compares with a calculated value -
after "<free_text>" is translated into a value

<IIF({<full_title>}{~=}{free_text},{},{ <free_text>})>

~~ means LIKE in the original value


~= means LIKE in the translated value

7 Mar 2016 Page 164


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Content Handling Configuration

What is … Content This is a facility to configure the options around Microsoft Word content
handling files. This configuration allows you to define valid Word Templates that
configuration are required to be attached to Word documents being imported.

You can also define valid formats for each level of the classification –
effectively restricting some classification levels to particular formats.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Content Classification / Content Handling
Handling settings
2. The Content Handling Configuration dialog is loaded:

For every element of the classification (root or child element), which is


displayed in the left hand part of the dialog, the following settings are
configurable:
 Settings cascade from parent classification – the settings of the
parent will be applied
 Valid Word Template(s): enter the names of the MS Word
templates e.g. Template.dot
 Select All formats are allowed to allow all formats, OR deselect

7 Mar 2016 Page 165


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

that and specify individual allowed formats:


 Click Add to add a new format
 In the screen that appears, enter the extension, matching
Documentum format, and page modifier as appropriate

 Click Save. Add another format (or the same with different
page modifiers if appropriate) – using the Move up / Move
down buttons as required.
 Alternatively, select an existing rule and click Edit to edit,
or Remove to remove.
 Enable unprotection of Word documents during checkin /
protection of Word documents during checkout as follows:
 Enter the Word property to interrogate which will
indicate whether protection is to be done
 Enter the value in this property that will indicate
that protection is to be done
 Enter the password to apply to switch on
protection / use to remove protection.
 Click Save to save the rules. Set other classification rules as
required.
 Click Close to close the Content Handling configuration.

7 Mar 2016 Page 166


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Scripts Configuration

What is … Scripts Configuration


This configuration allows you write JavaScript-style codes which will be
executed either when a new document is initialized, or when a
document’s properties are modified and saved.

How to set Scripts 1. From the CARA Start menu, select the Control Panel and click on
Classification / Scripts
2. In the screen that appears, select the classification to which the
population rules will apply:

7 Mar 2016 Page 167


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

3. To add a script, click the magnifying glass next to the script window.
A writing window appears:

4. Click OK to close the window.


5. Click Save to close the window and save the scripts.
NOTE: Post-procesing scripts are also executed on checkin after
documents are created.
Scripts can use a "template" variable that references to the original
document/template object. – sessionContext and – username are also
available.

7 Mar 2016 Page 168


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

MS Document Extraction

What is … MS Document Extraction


This configuration allows you to take properties or properties and content
from Microsoft documents when they get imported / checked in to the
docbase.

How to set MS 1. From the CARA Start menu, select the Control Panel and click on
Document Classification / Properties Extraction
Extraction
2. In the screen that appears, select the classification to which the
extraction rules will apply:

3. To set extraction rules, click Add in the extraction section. In the


screen that appears, select from either a text extraction or a Microsoft
Property, and the corresponding property to map the values into in
Documentum:

7 Mar 2016 Page 169


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

4. Click Save. In the main screen, either Add, Edit or Remove other
extraction rules, and finally click Save.
NOTE: to extract a property from Microsoft that is not listed on the
dropdown, for example custom properties, simply type in the name.
You can now also extract the second line until a break is located (ie if
there is wrapping).

Email extraction Email information can also be extracted from CARA 3.2.316 upwards.
The extraction options are as follows:

Note for emails:

7 Mar 2016 Page 170


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

1. If the email sender does not have '@' in it, leave it blank
2. If the sender name starts with "/O=", leave it blank
3. If not possible to extract the values above from the sender
properties, extract them from the PR_SENT_REPRESENTING*
properties

7 Mar 2016 Page 171


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

MS Document Population

What is … MS Document Population


This configuration allows you to take properties from Documentum when
Microsoft documents are checked out and populate the values into the MS
document properties.

How to set MS 6. From the CARA Start menu, select the Control Panel and click on
Document Classification / MS Document Population
Extraction
7. In the screen that appears, select the classification to which the
population rules will apply:

8. To set population rules, click Add in the population section. In the


screen that appears, select the Documentum Property, and the
corresponding Microsoft property to map the values into:

9. Click Save. In the main screen, either Add, Edit or Remove other
population rules, and finally click Save.
NOTE: to populate a property from Microsoft that is not listed on the
dropdown, for example custom properties, simply type in the name.

7 Mar 2016 Page 172


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

MS Word Field Merge

What is … MS Word Field Merge


This configuration allows you to take Documentum properties from an
object and pass the values into MS Word fields during creation of a
document from template only.

Setting up MS To set up the MS Word Field Merge, simple place MS Fields into the
Word Field Merge template document in Documentum, using the name of the attribute
whose value should be replaced in the field on creation.

7 Mar 2016 Page 173


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Forms (Properties and Custom Actions)


Configuration
Overview

What is … Forms The properties dialog (Form) displayed for each document can be tailored
configuration to suit the needs of the user opening those properties. Each Classification
can potentially have a different properties dialog displayed for each user /
group / world. This configuration allows those dialogs to be built and
tested.

Forms can also be configured in the Custom Actions – all the information
in this chapter also relates to creating a Form for a Custom Action.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Forms General / Forms
2. The Forms Configuration dialog is loaded
3. A configuration can be
 Viewed
 Edited
 Created

7 Mar 2016 Page 174


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Viewing a Forms Configuration

How to … view a 1. Open the Forms Configuration, choose any listed item representing an
Forms existing configuration and click Edit.
configuration

Note: the additional columns display information about the configuration:


 User or Group - user or group to which the configuration applies
 New/Import - displayed on New or Import document
 View / Edit - displayed when viewing or editing properties

2. The selected configuration is loaded in the Forms Configuration


dialog. NOTE: an example of the form appears next to the Forms
configuration screen so any changes made can instantly be seen
and tested.
3. To close the displayed configuration choose the option Cancel
4. To close and exit the Forms Configuration dialog select Close

7 Mar 2016 Page 175


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Please note  The name of a configuration is as follows:


[Text string name] (<object_type>)

 Any type that is part of the Classification (i.e. the type of subtypes on
which the Classification is based) can have multiple Forms
configurations, differentiated by the [Text string name].
 Any type that is NOT part of the Classification has just the
<object_type>.
 Note that you can have both, in which case:
Test Document (generis_document) - available for use in the
Classification
(generis_document) - will be displayed for any document of the type
where the attributes to not make it part of the Classification
 Check the Display preview option to see a preview of the form as
you configure it.

7 Mar 2016 Page 176


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Exporting a Forms configuration

What is export CARA allows you to export the XML file that defines the Forms
configuration.

How to… export a 1. Select the Forms configuration to export, and click Export.
Forms
configuration 2. In the screen that appears, select a directory to export the XML file to,
and select a name for the file:

3. Click Save. The Forms XML is exported.

7 Mar 2016 Page 177


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Creating a Properties Forms Configuration

Creating the form To create a new form, click Add:

Select whether the form is for all users, or only specific groups. Then
select if the form is valid for New and Import operations and/or View
and Edit operations.

Select the base object type. If the type is part of the overall CARA
Classification (main type or a subtype) you will be able to give the
configuration a specific name, otherwise the name will be set to the same
as the type name.

Modifying the form To modify the properties, select the form and click Properties. Then
properties adjust e.g. the group details or other settings as desired, as described
above.

7 Mar 2016 Page 178


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Editing a Forms Configuration

Setting up the form One the form is created, you can click on the root and click the Edit
button and set the form parameters (or double click on the root):

Please note: to set a particular height and width you can also just drag and
drop a corner and this will automatically set the values in the width and
height field.

Formatting labels – For all labels: if you add HTML formatting tags (e.g <b> </b>) before
prior to CARA v3.3 and after the label, you will get formatted text:

NOTE: this formatting is for backwards compatibility on existing


configurations, but formatting is now generally done through a separate
field called Style:

7 Mar 2016 Page 179


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Conditional All components of the CARA Forms can be made visible / invisible, or
visibility, mandatory / non-mandatory, or editable / read-only based on conditions
mandatory (values of certain attributes). The following applies to all sections below.
enforcement and
editability NOTE: from 3.7 you can use the variable ${user_name} in the condition.

NOTE: from 3.8 you can use any variable e.g. ${department}_managers.

Conditional If the component should be made editable or read-only depending on


editability conditions, check the Enable conditional editability box on the
Editability tab of the control. Choose whether, when the conditions are
met, to make the control editable – select from All¸Any, or Custom
(allows you to select multiple criteria and decide the AND / OR between
them).

Then click Add to add a condition:

If selecting Document property, select the property from the dropdown


and click Next. In the next screen, enter the conditional values (the
options will depend on the property type) and click Save

7 Mar 2016 Page 180


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

If selecting a folder path, click Next and enter the values:

If selecting a User Name or Group Name, click Next. Enter the


user/group condition and click Save:

Add other conditions (evaluated on AND basis).Add other conditions


(evaluated on AND basis).

Conditional If the component should only display in certain circumstances, check the
visibility Enable conditional visibility box on the Visibility tab of the control.
Choose whether, when the conditions are met, to Show or Hide the tab –
select from All¸Any, or Custom (allows you to select multiple criteria
and decide the AND / OR between them)

Then click Add to add a condition:

7 Mar 2016 Page 181


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

If selecting a folder path, click Next and enter the values:

If selecting Document property, select the property from the dropdown


and click Next. In the next screen, enter the conditional values (the
options will depend on the property type) and click Save

If selecting a User Name or Group Name, click Next. Enter the


user/group condition and click Save:

Add other conditions (evaluated on AND basis).Add other conditions


(evaluated on AND basis).

Conditional If the component should be made mandatory in certain circumstances,


mandatory check the Enable conditional mandatory enforcement box on the
enforcement Mandatory Enforcement tab of the control. Choose whether, when the
conditions are met, to make the control mandatory – select from All¸Any,
or Custom (allows you to select multiple criteria and decide the AND /

7 Mar 2016 Page 182


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

OR between them)

Then click Add to add a condition:

If selecting Document property, select the property from the dropdown


and click Next. In the next screen, enter the conditional values (the
options will depend on the property type) and click Save

If selecting a folder path, click Next and enter the values:

If selecting a User Name or Group Name, click Next. Enter the


user/group condition and click Save:

7 Mar 2016 Page 183


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Add other conditions (evaluated on AND basis).Add other conditions


(evaluated on AND basis).

Setting up tab and 1. Open the desired Forms configuration as described above.
column containers
2. Select the root of the tree (“Form”) and click Edit

3. Modify Title and Label of the Forms dialog, as well as the height and
width (leave at 0 to have CARA manage it for you). Click Save to
save the Form information.
4. Select the Tabs item in the tree and click Add / Tab to add a tab, or
select an existing tab and click Edit to edit a tab.

7 Mar 2016 Page 184


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

a. Enter an internal name for the tab


b. Enter a label for the tab OR select a label from the drop-down
of labels which comes from the Display Labels dictionary for
multi-lingual labels (see the chapter on Dictionaries in this
guide).
c. Enter a width (pixels) if the default is not desired.
d. Select whether to align the label to the Left, Top or Right or
Hidden
e. Enter a label style if required (see note on formatting at the
beginning of this section)
f. If the tab should only display in certain circumstances, check
the Enable conditional visibility box. See that section above.
g. Click Save to save the tab information.
OR
5. Select to use Columns instead, and insert a Column Container (this
will give a less-traditional view of properties in columns instead of
tabs e.g.:)

7 Mar 2016 Page 185


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

6. Once you have a column container, select it and click Add to add
columns. In the column definition screen, enter the column width
(%) and the label width (pixels). Also choose the label alignment
(including marking as hidden), and the conditional visibility as
appropriate.

Elements within CARA Forms configuration allows you to include elements inside each
Elements other. For example, inside a tab you can include multiple columns; inside
a fieldset under a tab you can set up a mini-tabbed area, and so on.

Setting up Fieldsets allow you to group multiple Forms with a visible border and a
Fieldsets heading:

7 Mar 2016 Page 186


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Select the parent control (e.g. Tab) and click Add, then select Fieldset.

Enter the Label for the fieldset (or select from the drop-down of available
multi-lingual values from the Display Labels dictionary). Define the
Width of the fieldset (pixels) and whether the label should be left, top or
right aligned or hidden. Also define any Label style and mark the
fieldset as collapsible (this provides the user with an arrow on the Forms
screen to collapse the field and thus provide more space on the visible
screen).

Define the Conditional Visibility as required, and then click save.

To add Forms into the grid, select the grid in the main Forms
configuration control list and add Forms as defined later in this section:

Setting up Grids Grid - For creating a grid (table) of related repeating value Forms.

7 Mar 2016 Page 187


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Or

Select the parent control (e.g. Tab) and click Add, then select Grid.

7 Mar 2016 Page 188


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Enter the Label for the grid (or select from the drop-down of available
multi-lingual values from the Display Labels dictionary). Enter a Label
style if required.

Define the Height of the grid (pixels) and whether it should be


Mandatory to have at least one row completed. You can also choose to
enable users to Import from Excel files containing tables of grid values,
which will automatically populate the grid.

To allow users to import data into the grid from an Excel spreadsheet,
check the Enable import from Excel box.

To have a popup for end users to create values for a new row (rather than
editing in place), check the Edit rows in a dialog option. If using this,
choose a Row edit dialog width (choosing 0 leaves the application
default).

Add any automatic values desired into the Row Initialization field.

In the Restrictions tab, define whether to disable row adding or disable


row removing. Also define whether or not to require a minimum or set a
maximum number of rows in the grid.

In the Visibility tab, define the Conditional Visibility as required, and


then click save.

In the Reset Properties tab, choose whether the grid should reset after a
change in any of the available attributes listed.

NOTE: "Reset properties" setting should only be configued when using


the option to edit rows in a dialog row editing.

After setting all these features as desired, click Save to close the window
and save the grid.

To add properties into the grid, select the grid in the main properties
configuration control list and add properties as defined later in this
section:

Important – if you are editing values in a grid using the popup dialog, and
want to have one field reset another on change and the second field is

7 Mar 2016 Page 189


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

dependent on the first by a query, use

In (‘${field1}’)

Rather than

= ‘${field1}’

Editing individual Select any individual property in the tree and click Edit, or select a tab,
properties column, fieldset or grid and click Add to add a new property. There are
tabs of settings common to all properties, and then each type of property
control has its own settings.

Individual For all individual properties, the heading of the dialog allows you to set
properties – basic an internal name (e.g. with some description), select the attribute to
settings which it is mapped, and choose whether the field is always Enabled and /
or Mandatory:

Common Settings Available settings on the Value Assistance tab relate to offering value
– Value assistance lists within the properties dialog and the different data source options:

TYPE: Query

Enter the query that will create the selection list for users. NOTE: there
is complex logic available with queries which is addressed later in this
section:

7 Mar 2016 Page 190


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

When querying more than one attribute (e.g. to map to other attributes, or
to display one and save another), use the Enable “order by” checkbox.
This will allow ordering by anything other than the first item in the query
(if you add the order by clause without this checkbox, it will be ignored).
However, note that the performance will be affected.

The asynchronous option allows you to show the filters only on e.g.
activation of the dropdown, or filtering of the values, to improve
performance. If there is a WHERE clause used in the query, this option
must be checked.

Freetext allowed will allow the user to add a value to the field that is not
in the value assistance list.

The default limit on queries is 200 results. To change this, enter some
value in the Query results limit field.

The Min autocomplete chars field allows you to specify the minimum
number of characters the user must type before the autocomplete is
activated (default is 3, if the field is empty then this is the value used).

DQL in VA can have one or two columns. If there is more than one, the
second one is used as a label.

TYPE: Value list

Enter the values (one per line) that will create the selection list for users.

7 Mar 2016 Page 191


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

The asynchronous option allows you to show the filters only on e.g.
activation of the dropdown, or filtering of the values, to improve
performance. If there is a WHERE clause used in the query, this option
must be checked.

Freetext allowed will allow the user to add a value to the field that is not
in the value assistance list.

The Min autocomplete chars field allows you to specify the minimum
number of characters the user must type before the autocomplete is
activated (default is 3, if the field is empty then this is the value used).

TYPE: Dictionary

Select the Dictionary that will provide the values for the property field.
If applicable, select the alias to display (including select “[per user
locale]” if this is available, which will drive local language values for
users when they select a different operating language for CARA Web).

NOTE: if you do not check the “Asynchronous” option, only the first 100
values of a dictionary will be loaded for performance reasons. If the
dictionary is larger, check “Asynchronous” and users can then use type-
ahead to enter a few characters in the field at which point the dictionary
list will filter from the complete list of items.

7 Mar 2016 Page 192


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Freetext allowed will allow the user to add a value to the field that is not
in the value assistance list.

The Min autocomplete chars field allows you to specify the minimum
number of characters the user must type before the autocomplete is
activated (default is 3, if the field is empty then this is the value used).

Refer to the Dictionary chapter, in the section about special aliases, to see
information about specific alias values “[per user locale]”

TYPE: Taxonomy

If the field is part of a taxonomy of values from several dictionaries, then


select the taxonomy, and if applicable select the properties which are on
higher levels of the taxonomy than the one you are editing (if this
property is the first level of the taxonomy, leave all the Level fields
empty).

The asynchronous option allows you to show the filters only on e.g.
activation of the dropdown, or filtering of the values, to improve
performance. If there is a WHERE clause used in the query, this option
must be checked.

Freetext allowed will allow the user to add a value to the field that is not
in the value assistance list.

7 Mar 2016 Page 193


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

The Min autocomplete chars field allows you to specify the minimum
number of characters the user must type before the autocomplete is
activated (default is 3, if the field is empty then this is the value used).

TYPE: Set Query

Special case value assistance: for text field controls only, the value
assistance is a “set” query, and sets the value to whatever is the first line
first attribute returned from a query, e.g.

Select distinct department_name from


custom_document where project = ‘123’ order
by department_name desc

TYPE: Script

This allows you to define a script which will provide the values for the
assistance, e.g.:

7 Mar 2016 Page 194


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

The script will be used to initialize available values. The valueAssistance


variable is a list reference that should be populated, e.g.
'valueAssistance.add(new MapEntry("key", "label"));'. The Documentum
session is available as 'session' variable. Object properties are available as
'model' variable.

Common settings On the Reset on change tab of the dialog you can specified which
– Reset on change (dependent) properties shall be cleared in the GUI whenever the current
attribute has been changed.

7 Mar 2016 Page 195


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

It is also possible to execute a script on change.

Common settings On the Reset Properties tab of the dialog you can specified which
– Reset Properties (dependent) properties shall be cleared in the GUI whenever the current
attribute has been changed.

7 Mar 2016 Page 196


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

(a)To select from existing Documentum properties select which loads


the property selection dialog.
(b)Select the desired properties from the list of properties, add it to the list
of selected properties by double click or using the add and/or
remove buttons. Click OK.

Common settings All field types allow definition of margins around the field, and in some
– Margins cases also of the height and width of the field itself or any secondary
popup. On the General tab, you will find a section like this:

Leaving the values empty will let the application use the default values.
Otherwise, set the values (in pixels) as desired.

Text field Single or multiple line textbox for freetext entry

7 Mar 2016 Page 197


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

On the General tab:

Enter a Label (or choose one from the drop-down of multi-lingual values
from the Display Labels dictionary). Provide a Tooltip text (or again
choose one from the drop-down of multi-lingual values from the Display
Labels dictionary).

Set a Label style if required. Set the Fixed Width (pixels) or leave it
blank to use the application defaults. Choose whether the field is single
or multiple lines.

If the field is designed to capture a password or other sensitive


information, considering checking the option Mask field as password
inputs.

Define the Margins as described on page 198.

7 Mar 2016 Page 198


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

On the Restrictions tab:

Define the maximum length (characters) of the entry field (which must
be equal to or less than the property definition otherwise the property
definition is enforced).

Enter a Mask to be applied to restrict what can be entered in the field,


where:
9 = integers 0-9
A = alphabetical characters A-Z or a-z
* = any alphanumeric character

For example, to require a phone number enter 999-999-9999

Define a Regex expression, e.g. ^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+$ for


email validation. If you want a message to be given to the users when
field validation fails, enter it in the Regex Message, or select a multi-
lingual value from the drop-down from the Display Labels dictionary.
This will give the user something like this:

If a text field is mapped to a repeating attribute, you can specify a


separator for the values (comma or new line) by putting \, or \n in the
separator field:

Label field Displays property value as non - editable label display. Note – putting
“Your Permissions” as the label, without choosing a property name, will
display the user’s permissions on a document.

7 Mar 2016 Page 199


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Enter a Label (or choose one from the drop-down of multi-lingual values
from the Display Labels dictionary). Provide a Tooltip text (or again
choose one from the drop-down of multi-lingual values from the Display
Labels dictionary).

Define a style for either / both the Label and the Text if desired.

Set a Fixed Width (pixels) or leave blank. Define the Margins as


described on page 198.

The Text or DQL field allows entry of fixed text (or HTML) or a DQL
statement as shown above.

Additionally, you can select that the label field displays an alias for the
attribute value, using a Dictionary with a specified or a [per user locale]
alias:

7 Mar 2016 Page 200


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Number (integer) Number field – will only accept integers


field

On the General tab:

Enter a Label (or choose one from the drop-down of multi-lingual values
from the Display Labels dictionary). Provide a Tooltip text (or again
choose one from the drop-down of multi-lingual values from the Display
Labels dictionary).

Define a label style if desired.

Set the Fixed Width (pixels) or leave it blank to use the application
defaults. Define the Margins as described on page 198.

On the Restrictions tab:

7 Mar 2016 Page 201


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Select whether to Allow Decimals, and optionally enter a minimum and


maximum value. Finally enter the format (e.g. 000, #,##0). Also select
whether to display as empty (and store as NULL) if the value is zero
(Display an empty value if the value is set to zero).

Date field Date field - Provides a date - picker calendar

On the General tab:

7 Mar 2016 Page 202


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Enter a Label (or choose one from the drop-down of multi-lingual values
from the Display Labels dictionary). Provide a Tooltip text (or again
choose one from the drop-down of multi-lingual values from the Display
Labels dictionary).

Define a label style if desired.

Set the Fixed Width (pixels) or leave it blank to use the application
defaults. Define the Margins as described on page 198.

On the Restrictions tab:

Optionally enter a minimum and maximum date value. These can be


Static Dates, or a Dynamic Date (choose another date attribute and a
number of days which the minimum date has to be greater than that by, or

7 Mar 2016 Page 203


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

the maximum has to be less than by), or based on the Current date
(again choose a number of days greater than or less than the current date
that are allowed for minimum and maximum respectively).

Date and Time field Adds a date and time combination field:

All the settings are the same as for a Date field above.

Checkbox Adds a check box for Boolean properties only.

On the General tab:

Enter a Label (or choose one from the drop-down of multi-lingual values
from the Display Labels dictionary). Provide a Tooltip text (or again
choose one from the drop-down of multi-lingual values from the Display
Labels dictionary).

Define a label style if desired. Define the Margins as described on page


198.

Set the Fixed Width (pixels) or leave it blank to use the application
defaults.

Checkbox group This allows repeating attributes to be displayed as a list of checkbox

7 Mar 2016 Page 204


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

items:

On the General tab:

Enter a Label (or choose one from the drop-down of multi-lingual values
from the Display Labels dictionary). Provide a Tooltip text (or again
choose one from the drop-down of multi-lingual values from the Display
Labels dictionary).

Define a label style if desired.

Set the Fixed Width (pixels) or leave it blank to use the application
defaults. Define the Margins as described on page 198.

Finally, decide whether to display the values in a horizontal or vertical


manner (as in the screenshot above).

Dual list field Dual list field - Provides secondary dialog with values list to pick
multiple values:

7 Mar 2016 Page 205


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

On the General tab:

7 Mar 2016 Page 206


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Enter a Label (or choose one from the drop-down of multi-lingual values
from the Display Labels dictionary). Provide a Tooltip text (or again
choose one from the drop-down of multi-lingual values from the Display
Labels dictionary).

Define a label style if desired.

Set the Fixed Width (pixels) and Fixed Height, or leave it blank to use
the application defaults.

Define the List template, which will govern how the list of values is
displayed. As for a combo, this allows the users to see a value row which
displays more than one attribute e.g. {user_name} – {user_os_name}
where the query might be select user_name, user_name, user_os_name
from dm_user where r_is_group = 0 order by 2. Note the use of the first
listed attribute as a key.

Define the Tooltip template, which will govern how the tooltip when
hovering over each value is displayed. This allows the users to see a
value row e.g. user_name but then have more information in the tooltip
e.g. user description.

Choose whether to Load available values on filter only which means


that, when accessing the values from the value assistance, values will
NOT be shown initially (e.g. useful if you have a very long list) but only
when the user filters the list (e.g. enters a few characters).

Define the Margins as described on page 198.

From version 3.5.2 repeating attributes can be used.

On the Restrictions tab:

Select whether there are to be a maximum number of allowed values


(blank = unlimited).

Combobox Combo Box - Drop - down list box of values:


(dropdown)

7 Mar 2016 Page 207


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

On the General tab:

Enter a Label (or choose one from the drop-down of multi-lingual values
from the Display Labels dictionary). Provide a Tooltip text (or again
choose one from the drop-down of multi-lingual values from the Display
Labels dictionary).

Define a label style if desired.

Use the All values listed when expanding a combo box option to
prevent the combo showing filtered results based on any selected value in
the field (without this, the user has to click X at the end of the field to
clear the existing value in order to see all values in the dropdown).\

Set the Fixed Width (pixels) or leave it blank to use the application
defaults.

Define the Margins as described on page 198.

See the notes in the following sections for using the List template and List
width (pixels, leaving this blank uses the application defaults).

7 Mar 2016 Page 208


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Combo Template / CARA has a unique feature built into the Combo handling, which allows
On Change a single combo to query and display multiple properties, and then update
Mapping / Special multiple properties.
Case DQL
First of all, on the Value Assistance tab, enter a particular DQL for
example

select authors, authors, keywords, study_number from cts_instance_info


where object_name = 'Study Information' and any lower(authors) like
'%${filter}%' order by 2

Note that in the above query, the first attribute listed is used as an index,
not for display, so you may need to enter a certain attribute twice.

Next, in the Combo Template field on the General tab, optionally add
how you would like the dropdown to display, e.g.

<b>{authors}</b> :: {keywords}

or

<table border=0><tr><td>{authors}</td><td>{keywords}</td><td
align="center">{study_number}</td></tr></table>

Finally, in the On Change Mapping field on the Mapping tab, enter


which attribute on the form should be set with which attribute result from
the query e.g.

study_number=study_number
site=keywords

This would result in the single combo showing (and setting) multiple
fields:

In a set of Combos used in a Grid control, you can:


1. Use $control with a row values
2. Reset the combo list on each row since it may be based on different
$control value

NOTE: The mapping now supports repeating attributes.

7 Mar 2016 Page 209


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Also, the mapping supports a SPLIT function, e.g.

repeating_field=split(single_field, "separator")

or default (by comma):

repeating_field=split(single_field)

On the Restrictions tab, you can enter a maximum field length for use e.g.
when the Combo also allows freetext entry:

Radio group Radio Group - creates a group of radio items – where user can select
from multiple values to store a single one in a property:

On the General tab:

Enter a Label (or choose one from the drop-down of multi-lingual values
from the Display Labels dictionary). Provide a Tooltip text (or again

7 Mar 2016 Page 210


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

choose one from the drop-down of multi-lingual values from the Display
Labels dictionary).

Define a label style if desired. Define the Margins as described on page


198.

Set the Fixed Width (pixels) or leave it blank to use the application
defaults. Finally, decide whether to display the values in a horizontal or
vertical manner.

Objects grid It is possible to define an ID field as an Object grid – this allows users to
import / create new documents from the properties screen of a first
document, and have the resultant IDs stored in the ID attribute, with a full
display of the documents:

Note that the attribute used for an Objects grid MUST be a repeating ID
type.

On the General tab:

Enter a Label (or choose one from the drop-down of multi-lingual values

7 Mar 2016 Page 211


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

from the Display Labels dictionary). Provide a Tooltip text (or again
choose one from the drop-down of multi-lingual values from the Display
Labels dictionary).

Set a Label style if required. Set the Fixed Width (pixels) or leave it
blank to use the application defaults. Set the Grid Height or leave it
empty to have the application default used.

Define the Margins as described on page 198.

On the View settings tab:

Select the View to use for the columns in the grid (this can make use of
views which are marked hidden in the View Management and therefore
not available for column display in the Explorer window).

Choose one or more New Item Shortcuts as defined on the view to use for
adding documents to the grid.

Decide whether to Allow adding existing objects using a dashboard. If


you select this option, choose a label for the button which will open the
Dashboard, then enter the Dashboard name and Report name. You can
also map variables e.g. prepopulate some dashboard form fields with
values from the attributes of the document.

Finally, choose the following Options:

7 Mar 2016 Page 212


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

 Hide format icon – Hide the column that displays the format icon
of the document in the grid
 Hide lock icon - Hide the column that displays the checkout / lock
icon of the document in the grid
 Disable objects removing – disable the user from removing
objects once added to the grid

Saving the To save the altered configuration choose the option Save.
properties

7 Mar 2016 Page 213


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Create a New Forms Configuration

How to … create a 1. From the Configuration for list box within the Forms Configuration
new configuration dialog, choose Add, or select an existing configuration and choose
Duplicate to start from an existing configuration.
2. The New Forms Configuration dialog is loaded offering the following
options:

 User or Group:
Select Users to either provide one dialog for a) all users or b) one
specific user.
Select Groups to provide different dialogs for different groups.
 Selected User or Group:
In case Users has been selected in the previous step select All
Users or a specific user name
In case Groups has been selected in the previous step select a
specific group.
(Other properties dialogs can be created for a different user or a
different group in a separate step)
 New Import Properties:
Select this checkbox for the properties configuration to be
displayed during the New and Import process
 View Edit Properties:
Select this checkbox for the properties configuration to be

7 Mar 2016 Page 214


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

displayed during the View and Edit process


 Base Object Type:
Select the object type this configuration shall be valid for. This
includes sub types of the selected object type.
8. The configuration is created and loaded in the Forms Configuration
dialog. Modify the configuration as required. For details refer to the
previous section “Editing Forms Configuration”.

7 Mar 2016 Page 215


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Check in from file / copy configuration

How to … copy a To quickly copy one configuration to another, simply do the following:
configuration by
checking in from 1. Create both configurations.
file 2. In the first configuration, create all the options required.
3. Select the configuration and click Export to export the XML file
to a location on the file system.
4. Select the second configuration (it does NOT have to be checked
out to begin this process), and click the Check in button. Select
the XML file to check in:

5. Click Open. On the next screen, select the checkin option and
click OK.

7 Mar 2016 Page 216


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Deleting a configuration

How to … Delete a To delete a form configuration used for Properties, select the form and
form configuration click Delete. You will be offered options to completely delete the
configuration (which marks it all as hidden) or just remove the current
version (thus reverting to the previous version). Choose the option and
click OK:

7 Mar 2016 Page 217


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Properties DQL

Select, set Both DQL select and set statements can be used in the DQL for a
property control.

Example select statement:


select distinct department_name from
dm_dbo.company_info where department_name

For repeating properties add the part in bold:


select <property_name> from dm_dbo.company_info
where any <property_name>

IMPORTANT NOTE FROM VERSION 3.1.269+

The DQL definition format has changed to support use of multiple


attributes in the DQL. The first attribute is a key, the second is a
displayed value, and all others can be used in combo template definition.
Additionally the DQL cannot end with something like
"where <attribute>".

It now has to be a complete DQL with a keyword "${filter}" - this will


be replaced with the characters entered by a user to filter the list using
typeahead. (Note that the number of results is limited to 200 due to
performance reasons (making the type-ahead recommended). For
example:

select r_object_id, object_name from dm_folder


where object_name like '%${filter}%' order by 2

Where: r_object_id is a key, object_name is a displayed value, filtering is


by object_name

If there is just one attribute used, it will be treated as a key and as a


displayed value. e.g.

select user_name from dm_user where user_name


like '%${filter}%' order by 1

Additionally there is a new option to define a template for a combo to


display more advanced results as in the example below:

<tpl for="."><div class="search-


item"><h3>{object_name}<span>{r_creation_date:dat
e("MM/dd/y")}<br />by

7 Mar 2016 Page 218


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

{owner_name}</span></h3>{r_version_label}<br
/></div></tpl>

Item selector:

div.search-item

Note that now UNION clauses are also supported.

Also, you can use the AS clause with a UNION, e.g.

select user_name as my_user from dm_user union


select group_name as my_user from dm_group order
by 1

$control() This can be used to get the value from another control. Replace
“<property>” with the internal name of the property associated with the
desired control.

$control(<property>) - this is a standard control that is populated using


the attribute of the object contained in the parenthesis.

Dependent If you have two properties linked through a taxonomy, the 2nd and lower
properties levels must be set to “Asynchronous” in order to ensure the right list is
loaded depending on the higher level property value.

You cannot have properties linked through a taxonomy if they are


repeating.

7 Mar 2016 Page 219


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Document Category Configuration


Creating, modifying and deleting categories

What is … Any collection of documents returned by a valid DQL statement.


Categories allow for a very granular configuration setup.

How to … create a 1. From the CARA Start menu, select the Control Panel and click on
document Categories / Category definition
category
2. The Document Categories dialog is loaded:

3. Within the Category Details section of the dialog enter


 Name: as a label for the category to be created
(Maps to the object_name field of the configuration object)
 Type: What object type (including subtypes according to the
object type hierarchy) this is based on
 DQL where: Enter the DQL query from the where condition (e.g.
owner_name = ‘dmadmin’)
 Whether or not the category applies to all versions
4. Click Save to save the configuration, or Reset to reset it.

Continued on next page

7 Mar 2016 Page 220


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Creating, modifying and deleting categories, Continued

How to … edit a Open the Category configuration as above. Select a category and modify
document the details, clicking Save at the end.
category

How to … delete a Open the Category configuration as above. Select a category and click
document Remove. Click Yes to the confirmation:
category

7 Mar 2016 Page 221


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Special case categories

System categories There are several categories which are “special case” categories as they
can help define certain admin or system functions, or which are generally
useful.

Category name Description Definition


All Documents Defines the default view for filter Type: dm_document
(this is the DQL applied for DQL: 1=1
unfiltered view). By default set to All versions: No
the DQL on the right, if you want to
be able to see all dm_sysobjects,
modify this to be based on
dm_sysobject.
Audit Autopromote Defines what documents should be Type: dm_document
audited during autopromote method DQL: 1=1
running: typically might be defined All versions: No
as:
Email Templates Defines the folder locations and Type: dm_document
security for Email template objects. DQL: where
NOTE: add this category to your folder('/System/Applications/
Linking Configuration at the top of CARA3/Workflows
the list as “Manual linking” and add Notifications',descend)
the category to the Security All versions: No
Configuration at the top of the list
specifying “CARA Configuration”
PDF Watermarked Documents Category of documents which should Type: <user defined>
be treated with DocSecure when DQL: <user defined>
opening from CARA All versions: No
Structures CARA Structure objects Type: <user defined>
DQL: a_content_type='gtoc2'
All versions: No
Templates Documents in the Templates cabinet Type: <user defined>
DQL: folder('/Templates',descend)
All versions: No

7 Mar 2016 Page 222


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Audit Configuration

What is … audit The audit trail is a log of events that take place on a document. These
trail audit trail events can be configured through CARA to enable systems to
meet 21 CFR part 11 requirements for electronic records.

Please note  Auditable events are configured per document category. In case a
document exists in more than one category the highest level of
auditing will be applied.

How to … add a 1. From the CARA Start menu, select the Control Panel and click on
new audit Categories / Audit Configuration:
configuration

2. Add a Document category by selecting Add in the corresponding


dialog section:

3. Select the desired Category and select OK


4. Add Audit Events by highlighting a category in the left hand list and

7 Mar 2016 Page 223


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

choosing Add in the corresponding section of the dialog.


5. Within the Add/Modify Audit Event dialog Select any available
auditable event from the Event Name list

6. Choose whether a Signature is required or not. Additionally, if a


signature is required specify the text to be placed in the signature
dialog for the users to read.
7. Choose from the Reason/meaning/capacity options:
a. Not required
b. Required - freetext: enter a Default Value in the text field if
required.
c. Required - value from dictionary: select a dictionary from
the drop-down list, and also select whether Dictionary may be
overtyped by user. Optionally select a default value from the
dictionary using the drop-down list.
8. For (b) and (c) above also optionally enter the Reason label for the
“Reason/meaning/capacity” – if blank, the default is used.
9. Choose OK to accept these setting or Cancel to discard them.
9. Choose Save to store or Close to discard the audit settings. Confirm
the desired action in the subsequent confirmation dialog.

How to … edit an Open the Audit configuration as above. Select a category and an audit
audit definition

7 Mar 2016 Page 224


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

event, click Details¸ modify the details, and click Save at the end.

Sequence of The categories listed on the left hand side in the Audit Configuration
categories screen can be re-ordered via Drag and Drop.

How to … delete a Open the Audit configuration as above. Select a category and click
document Remove. Click Yes to the confirmation:
category

Or, for a particular category, select an audit event and click Remove.

Task auditing To enable detailed task auditing, each Task Type existing on the system
will have a number of audit events available to it:

So each task event can have separate auditing, dictionary reasons for
signature and so on.

7 Mar 2016 Page 225


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

ACL Template Builder

What is … ACL:
Documentum Access Control List managing information on the access
rights of objects.
Template ACL:
An ACL that is not constructed explicitly but built by the system
dependent on property values, e.g. for a lifecycle with 2 status levels
(Draft, Approved) the template ACL would define ACLs for
“<status>_document” and the system would build 2 ACLs
“Draft_document” and “Approved_document”.

How to … create 1. From the CARA Start menu, select the Control Panel and click on
an ACL Template Categories / ACL Template Builder
2. The ACL Template Builder dialog is loaded:

7 Mar 2016 Page 226


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

3. Click Add to add a new template

4. Select the Base Object Type the template ACL is created for from the
list of available types. The offered types are according to the base
object type setting in the Classification Configuration.
5. Define the naming scheme of the template ACL: Select a property
from the list of Available Properties and add it to the ACL Name text
box using the add button or via double click on the desired
available property. ACLs will be created based on all possible
permutations of the naming variables, at the time that a document
with the particular permutation is being created.
6. Add any “static” text to the ACL Name text box
7. Keep in mind that the resulting ACL may not have a name exceeding
32 characters.
8. Choose Add to store the new template ACL and Save in the ACL
Template Builder screen. Follow the steps in the next section below
to define the settings of the ACL template.

Please note  Calculated ACL Names that exceed 32 characters will not be created
and the document will be assigned a default ACL.
 Whenever a repeating attribute is used in ACL Template name or as a
group name in that Template, only the first value is used, unless the
ACL is private - contains <r_object_id> in the name..

How to … define 1. From the CARA Start menu, select the Control Panel and click on
the settings of an Categories / ACL Template Builder
ACL Template
2. The ACL Template Builder dialog is loaded:

7 Mar 2016 Page 227


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

3. Select the template to be defined and click Edit.

4. The ACL Template can be modified in the following ways:


a. Add Accessor
 Select the root element (name of the ACL template, here:
<a_status> Document) and choose Add.
 Add Accessor Name dialog loaded.

 Select Users or Groups or Template Group from the list box


and select the actual user or group by double click or using
the button.
Note: If the name of the template includes r_object_id, all attributes

7 Mar 2016 Page 228


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

will be available for selection in the Template Group name.


 Choose OK to add the selected user or group as an accessor
to the template ACL, Cancel to discard the selection
b. Edit (default) Accessor Permission
To grant access regardless of the current value of the
<variable> part of the template ACL name (in this example
<a_status>)
 Select the accessor’s default is entry and choose Edit
 Modify Accessor Permission dialog loaded.

 Select one of the seven Documentum Permit levels and


check if desired the Change State and/or Change Owner
extended permit checkboxes.
c. Add Accessor Permission
To grant access depending on the current value of the
<variable> part of the template ACL name (in this example
<a_status>)
 Select the accessor entry and choose Edit
 Modify Accessor Permission dialog loaded.
Select the Property to be evaluated from the Property list
box and enter the value for this access setting applies
 Select one of the seven Documentum Permit levels and
check if desired the Change State and/or Change Owner
extended permit checkboxes.

7 Mar 2016 Page 229


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

d. Delete Accessor Permission


Select the accessor permission to delete within the Edit ACL
Template dialog and choose Delete. Confirm this action.
Default is … accessor permissions cannot be deleted, modify
this entry to the desired access level e.g. None.
e. Delete Accessor
Select the accessor name to delete within the Edit ACL
Template dialog and choose Delete. Confirm this action.
5. Save any changes made.

How to … delete a 1. Within the ACL Template Builder select the template ACL to delete
template ACL and choose Delete.
2. Confirm deletion of the template ACL

Please note  Deleting an ACL template will affect any Security Configuration
based on that template (see next section).
 Deleting an ACL template will not delete the ACLs created using that
template, which will still be applied to the documents concerned.

7 Mar 2016 Page 230


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Security Configuration

What is … Security The Security Configuration allows you to define a Template or Standard
Configuration ACL to apply to a particular category of documents.

How to … 1. From the CARA Start menu, select the Control Panel and click on
Categories / Security Configuration
2. The Document Security Configuration dialog is loaded:

3. Add, Edit, Delete or Reorder a Category – Template ACL assignment:


4. To add new assignments choose Add.

Select a Document Category form the first list box and the desired
Template or static ACL from the second. Optionally, if the document
show have the calculated ACL set only initially and then allow
manual permissions changes, check the box Calculate initially then

7 Mar 2016 Page 231


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

allow manual security. Choose Save to store this setting or Cancel


to discard it.
5. To edit an existing assignment select an existing assignment and
choose Edit. Modify the setting by choosing a different template or
static ACL from the second list box.
6. To delete an existing assignment select an existing assignment and
choose Delete. Confirm in the subsequent confirmation dialog.
7. To reorder the list of assignments select an existing assignment and
move it up/down in the list by using the corresponding button and
. NOTE: ACLs are applied in the order in which the categories
are listed: so the first category that applies to a document is the one
used to define the ACL applied, making the order important.

Please note  The assignment between document category and ACL template are
applied in the order specified. ACL assignment will be for the first
document category for which the document applies.

7 Mar 2016 Page 232


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Linking Configuration

What is … Linking Configuration


CARA allows automatic linking of documents to folders based on
property values (again, driven by rules based on Document Category).
Missing folders are created. Manual linking is also permitted.

How to … manage 1. From the CARA Start menu, select the Control Panel and click on
linking Categories / Linking Configuration
configuration
2. The Linking Configuration dialog is loaded:

3. Create, Edit, Delete or Reorder a Linking scheme


3.1. To create a new linking scheme select Insert (note that each
category can have multiple linking paths defined, which will link
documents to multiple locations):

7 Mar 2016 Page 233


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

 Select a Document Category


 Construct the link path by using any combination of property,
dictionary or fixed values.
 Or alternatively to specifying the link path select that Linking
is manual for this category, which allows for manual linking
based on the location during document creation, etc.
 If you want to Prevent duplicates in a folder (based on the
object_name) check that option, and enter a path (using the
same logic as above) where duplicates should be moved to.
 Select Save to store these settings or Cancel to discard them
3.2. To edit an existing linking scheme select the desired linking
scheme for a category and choose Modify, apply any required
changes and choose Save or Cancel.
3.3. To delete an existing linking scheme select the desired linking
scheme for a category and choose Remove
3.4. To reorder the list of linking schemes select an existing category
and move it up/down in the list by using the corresponding button
and .
4. Save or discard (Cancel) changes

Using substrings It is possible to use substrings to get a value for a folder path creation.
Simply use the following:
substr(2) returns everything after second char
substr(0,4) returns first 4 chars

7 Mar 2016 Page 234


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

substr(-2) returns last 2 chars


substr(-3,1) returns third char from the end
substr(0,-6) returns string minus last 6 chars

For example
/Quality Documents/Originating Year <case_id,substr(0,-6)>/Project ending in
<project_number,substr(-1)>

Would give the following path for case_id 2004000012 and


project_number 1000045
/Quality Documents/Originating Year 2004/Project ending in 5

Defining custom To define a custom folder type at a particular level use the following
folder types syntax:
/Folder[dm_folder]/<attribute>[custom_folder]

Using Grouping You can create a folder structure where documents are grouping
according to an attribute, e.g. /Keywords/<keywords,group(0,1)>. It
works in the same way as substr, but adds the full value to the path after
the substring, e.g. for a Keywords value “Specification” in the above
example you would get the following folders:
/ S / Specification

Repeating If you have two repeating attributes used for linking configuration, then
attributes all permutations of those attributes are taken, e.g. for 2 values in each
attribute you get 4 link paths). To link based on the index position (ie
attribute1[0] / attribute2[0] and attribute1[1] / attribute2[1], put some
indicator in front of the attribute name (the string used is not important, it
just has to match and be a single character e.g.)
/ Cabinet / <a.keywords> / <a.authors>

Using dates If you use a date attribute in the linking configuration, the date will
translate to a folder name as follows:
<date_attribute>
will be translated into string with format yyyy-mm-dd
<date_attribute,format>
will be translated into string with specified 'format'

7 Mar 2016 Page 235


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Versioning Configuration
NOTE: previously called Check In / Checkout Configuration

What is … Check in configuration


This is a facility to configure which categories of documents should be
denied the ability to be checked in as the next major version. This
functionality may be desired when you want to restrict major versions of
a document based on a status change and/or lifecycle promotion.

Checkout configuration
This is a facility to configure which categories of documents should be
denied the ability to be checked out regardless of a user’s permissions on
the document. This functionality may be desired when a user needs
WRITE permission on an Approved document in order to be able to edit
its properties, but you don’t want them to be able to edit the content.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure General Versioning Configuration
Check In settings
2. The Versioning Configuration dialog is loaded:

7 Mar 2016 Page 236


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

3. The following options that can be configured.


 Deny checkout – disallows checkout even if the user has
VERSION or higher permission
 Deny Major Version – disallows checkin as major version
 Deny Minor Version – disallows checkin as minor version
 Deny Same Version – disallows checkin as same version
 Validate mandatory properties on check-in – validates that
mandatory properties are not empty on checkin.
 Prevent label change – disables the ability for the user to enter a
Version Label manually.
 Deny branching – denies checking in as branch version (NOTE:
the categories defined for this MUST have the “All Versions”
option checked in order for this to be effective).
 Deny check-in as not current version – removes the checkbox
“Make this the current version” from the Checkin screen.
4. To update any of these configurations, click on the Update button
next to the option. The Select Document Categories dialog is loaded:

5. Add or remove Categories and click Save.


6. On the main screen click Save to save changes

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Check In

7 Mar 2016 Page 237


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Label settings Categories / Check-in/out Configuration


2. The Check-in/out Configuration dialog is loaded. Go to the second
tab:

3. Enter a name for a rule, and the associated DQL statement. For
example, to keep the CURRENT version flag on previous Effective or
Approved versions of documents, you would enter the following:
 Label: Draft
 DQL: select r_object_id,a_status from dm_sysobject (all) where
i_chronicle_id in (select i_chronicle_id from dm_sysobject(all)
where r_object_id = '${r_object_id}') AND (ANY
r_version_label='Effective' or any r_version_label='Approved')
4. On the main screen click Save to save changes

Please note  Selected options can be left blank if this configuration option is not
desired.

7 Mar 2016 Page 238


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Content Access Configuration

What is … Content access configuration


This allows you to restrict access to primary content (as opposed to e.g. a
PDF rendition) for certain groups. For example, you may want users to
only be able to view a PDF rendition not the Word primary content for an
SOP, both of which they could normally do with READ permission.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Content Categories / Content Access Configuration
Access settings

2. Click Add to add a rule for a new category – select the category from
the list and click OK.

3. For each category you add, select it in the list and click the DOWN
arrow to edit the users/groups, or Delete to remove it from the list.
4. If you edit, then simply select the groups which should be disallowed
access to the primary content (other groups allowed – NOTE that if no

7 Mar 2016 Page 239


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

groups are listed, all groups are allowed normal access):

7 Mar 2016 Page 240


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Status Change Configuration


(NOTE – up to CARA v3.4 only, from 3.5 please refer to the Lifecycle Configuration chapter)

What is … Status Change configuration


This configuration allows you to define rules relating to changing status –
who can do it, under what circumstances, and whether or not to validate
that mandatory properties are complete.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Status Categories / Status Change Configuration
Change settings
2. On the Accessibility tab, you can add rules about who can change
status on documents:

3. To add a rule, click Add.

7 Mar 2016 Page 241


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

4. In the screen that appears, optionally select the Lifecycle name to


which the rule applies. Not selecting a Lifecycle will apply the rule to
all lifecycles.
5. Optionally select the State name to which the rule applies, if you
have selected a Lifecycle Name. Not selecting a State will apply the
rule to all states
6. Select a Document category to which the rule applies.
7. In the Promote can only and Demote can only fields, click the drop-
down to select the group(s) who have rights to promote and / or
demote documents (demote includes “return to base” function):

7 Mar 2016 Page 242


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

8. Select whether structure coordinators can promote and / or demote


within a structure view (if they are, for example, denied the ability to
do that through the Promote can only / Demote can only groups).
9. Click Save to save the rule.
To modify a rule, select it and click Modify and change the settings as
above.
To delete a rule, select it and click Delete.

Properties To set up validation of mandatory properties being completed on status


validation change, switch to the Properties validation tab.

7 Mar 2016 Page 243


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

1. To add a rule, click Add.

2. In the screen that appears, optionally select the Lifecycle name to


which the rule applies. Not selecting a Lifecycle will apply the rule to
all lifecycles.
3. Optionally select the State name to which the rule applies, if you
have selected a Lifecycle Name. Not selecting a State will apply the
rule to all states.
4. Select a Document category to which the rule applies.
5. Select whether to validate properties on promotion and / or demotion.
6. Click Save to save the rule.
To modify a rule, select it and click Modify and change the settings as
above.
To delete a rule, select it and click Delete.

7 Mar 2016 Page 244


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Document Rendering Configuration

What is … Document rendering configuration


This is a facility to configure the document rendering options. This
allows you to define local rendering queues in a distributed content
environment.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure New Categories / Document Rendering
Document settings
2. The Document Rendering Configuration dialog is loaded:

3. Click Add, or select the appropriate config and click Edit to access
the settings. The Modify Document Rendering Configuration dialog
is loaded;

NOTE: if you do not have any existing rendering configurations, you


will be asked whether you would like CARA to automatically create
some that match using the CARA Rendering Services engine:

4. Open the automatically generated ones to modify, or if you clicked


No above, then enter the information as required:

7 Mar 2016 Page 245


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

5. Choose whether to Use for manual PDF rendition requests


6. Click on the dropdown to select the appropriate Render Queue
Name.
7. Define an appropriate Event Name and a Message to be displayed as
desired.
8. From the Modify Document Rendering Configuration dialog, click
Update to define the categories of documents to be sent to this
rendering queue. The Select Document Categories dialog is
displayed:

9. Click Save to save the changes.


Note that if you are using the group cara3_users to determine which users
can login to CARA, then you should add the rendering user to that group.

IMPORTANT – You should at a minimum probably have two configuration, one with the

7 Mar 2016 Page 246


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

manual vs “use for manual PDF rendition requests” checked, and one not. That
automatic way, rendition requests will be sent correctly whether manually requested
or triggered by e.g. status change or checkin.

7 Mar 2016 Page 247


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Legal Hold

What is … Legal Hold


Any document that is in a category listed in the Legal Hold configuration
in CARA cannot be modified or deleted by any user through CARA,
regardless of their permissions.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Legal Categories / Legal Hold Items
Hold
2. The Legal Hold Items dialog is loaded:

3. Click Add on the left to select a category to add to the list, and click
OK:

4. Select the category on the left, and on the right either check “All
Users and Groups” or click the arrow to select specific users and
groups for whom to apply the Legal Hold. Finally click Save.

7 Mar 2016 Page 248


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Additional Legal CARA allows selective restriction on functionality that can also be used
Hold notes for Legal Hold purposes. For example, you can create a category for
documents to be held, and
- Deny checkin as same version (Checkin Checkout Configuration)
- Deny checkout (Checkin Checkout Configuration)
- Deny Status Change (Status Change Configuration)
- Prevent changes to particular properties (Properties Configuration
selective enable / disable fields based on rules)

7 Mar 2016 Page 249


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

DCN Configuration

What is … DCN DCN (Document Control Numbering) is a way of applying an


incremental number to a document without using the CARA Sequences
functionality (e.g. for customers who already have some database-level
incremental numbering).

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Legal Categories / DCN Config
Hold
2. The DCN Config dialog is loaded:

3. Click Add on the left to select a category to add to the list. Click OK:

4. Select the category on the left, and on the right click the arrow to
select specific users and groups for whom to allow DCN processing.
Finally click Save.

7 Mar 2016 Page 250


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Automatic Change Notifications

What are … Automatic Change Notifications allow users to be updated when


Automatic Change documents of particular interest to them are modified in some way.
Notifications

How to … 1. From the CARA Start menu, select the Control Panel and click
configure on Categories / Automatic Change Notifications
Automatic Change
Notifications 2. The Automatic Change Notifications dialog is loaded:

3. Click Add on the left to select a category to add to the list. Click OK:

4. Select the category on the left, and on the right click the arrow to
select specific users and groups who will receive automatic emails
notifying them of changes to documents in the category.
5. To use a user name or group name that will be dynamic (ie
calculated) choose Dynamic Recipient from the dropdown and enter

7 Mar 2016 Page 251


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

the name using <> to enclosed the name of an attribute on the


document e.g.

6. To have notifications sent ONLY when a particular lifecycle state is


reached enter the name of the state (freetext). Leaving this field blank
will notify users on all changes:

7. Finally click Save.

The following email templates are available:


 DocumentChange
 DocumentCheckIn
 DocumentStateChange
 DocumentPermissionsChange
Change notifications are sent on the following events: properties change,
checkin, state change, permissions change

7 Mar 2016 Page 252


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Category Scripts

What are … These are scripts that will be executed post0save on any documents in
Category Scripts that category. The script itself would be a JavaScript-style code where
'object' variable is a Documentum object and can be used to modify
object properties. E.g. 'object.setString("owner_name",
session.getUser(null).getUserName());'. DFC classes as well as Java
classes can be used. Documentum session is available as 'session'
variable. – sessionContext and – username are also available.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Category Categories / Scripts. The Scripts dialog is loaded:
Scripts

2. Click Add on the left to select a category to add to the list. Click OK:
3. Select the category on the left, and on the right enter the script to
execute on documents in the category. Finally click Save.
NOTE: Because category scripts are based on a DQL, cannot be
executed before the document is saved/checked-in. Because of that script
can be executed after check-in and is executed on the JMS as a superuser.
Classification scripts are executed during saving/execution, so you can
use them without such restrictions.
Scripts can use a "template" variable that references to the original
document/template object.

7 Mar 2016 Page 253


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Purge Configuration

What is … Purge This configuration allows you to define categories of documents to purge,
Configuration including associated objects such as relations, annotations, virtual
document links and audit trail entries.

How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Category Categories / Purge Configuration
Scripts
2. The Purge Configuration dialog is loaded:

3. Click Add to select a category to add to the list.


4. Select the category, and the date trigger and property (e.g. 1 day after
r_modify_date).

5. Select whether also to delete relations, annotations, audit trail


entries, and whether to unlink from Virtual Documents. Finally
click Save.

7 Mar 2016 Page 254


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Task Configuration
Task Types

What is… Task Type


The workflow within CARA is based on configurable task types – any
number of tasks types can be created (including those not related to
document content, but which might need to come before a document is
created, e.g. “Enter data”). Each task type can have multiple completion
statuses (see the previous section for configuring those) and have various
notifications and durations applied. In addition, dynamic permissions are
enabled by choosing a permission level to add on the document’s ACL
for the task recipient when the task is active – and this permission is
removed as soon as the task is completed. Finally, audit trail information
and electronic signature can be requested.

How to… add or 1. From the CARA Start menu, select the Control Panel and click on
remove Task General / Task Types
Types
2. The Task Types dialog appears.

3. Click Add to add a new task type and follow the instructions below.
Select an existing task and click Edit to edit it (proceed with the steps
below) or Remove to remove it.

7 Mar 2016 Page 255


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

How to… define a 1. Once the selected task definition screen is open, you can set the
task type details. The Name field is disabled when editing an existing task
type. The Name will be displayed to the users unless a Label is
entered (or selected from the Display Labels dictionary dropdown)

2. Choose a permission level to be granted to the recipient under


Permit Assigned.
3. Choose a permission level required by the task issuer to issue the
task under Permit required to create a task (optional)
4. Create one or more Completion Status values. To do this, click
Add and enter a value as well as checking whether the Completion
Status is considered satisfactory (positive) or not (negative):

7 Mar 2016 Page 256


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

5. In the popup, the Status Name will be displayed to the users


unless a Label is entered (or selected from the Display Labels
dictionary dropdown)
6. Optionally, enter a validation script. This script used to validate
whether the task can be completed with the selected completion
status. The 'task' variable references the task object, 'object'
variable references the related document. Documentum session is
available as 'session'
variable.taskCompletionStatusConfigDialogNewStatus=New
completion status
7. Select a default duration (number of days).
8. Select whether the recipients of such a task should be forced to
complete it in
 Serial
 Parallel
or the person sending the task be allowed to choose (“Any”)
9. Select Autostart if the task is to be started automatically as soon
as it is issued
10. In the Restrictions section select if the task can only be issued by
a particular Group and / or on a particular document Category.
11. Select if the option to manually change status on a document
while a task of this type is active should be disabled under Disable
manual status change when workflow is active
12. Select or deselect Allow changes once started which will allow
tasks to be delegated by the recipient or re-assigned by the task

7 Mar 2016 Page 257


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

owner once started.


13. Click Add next to the notifications to add a notification (or
highlight an existing notification and click Remove to remove that
notification). In the notifications dialog, choose the event, the
recipients for the notification, and the reminder(s) if appropriate,
and click Save. Repeat to add further notifications if required.
Note that the >> arrow will enter your own user information into
the dialog as a shortcut.

Special case task When creating a workflow in CARA Web, the option “Ad-hoc task or
type sequence” will appear based on whether or not there is a task type called
“Ad-hoc” set up. If there is no such task type (the settings of the task
type are unimportant) then the option to ad-hoc tasks is not available, and
only template workflows may be selected.

Task status The following is the mapping between the cara_activity task status and
the internal integer:
0 – Planned / 1 – Issued / 2 – Started / 3 - Finished

7 Mar 2016 Page 258


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Task Templates

What is… a Task A task template is a predefined set of tasks (one or more) that follow
Template certain rules and sequences.

How to create a 1. From the Tasks menu, click Task Template Configuration (or
task template access via the Tasks tab on the Control Panel).
2. The Task Template Manager screen appears. Click Add.

3. The Add Task Template window appears.

7 Mar 2016 Page 259


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Continued on next page

7 Mar 2016 Page 260


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Task Templates, Continued

How to create a 4. Enter a Name for the Task Template.


task template,
(cont’d) 5. Optionally, enter a Description for the Task Template.
6. Optionally enter a Bound document version label e.g. Approved to
override the default behavior (Document version label bound to the
task, by default it is set to an implicit version for task types that are
configured to grant RELATE or lower permission, or CURRENT
version for task types that grant VERSION or higher permission).
7. Check the Active? option to make the Task Template available for
use.
8. Check the Only allow one instance at a time? option to prevent
multiple workflows on the document.
9. Check the Prevent task sequence change option to prevent users re-
ordering the steps in the task sequence.
10. Check the Validate document properties on creation option to
require mandatory task properties be completed.
11. Choose whether to Deny creating on a document without PDF
rendition
12. You can also choose to Delete task if it not started by the due date
13. In the Associated lifecycle section, choose a lifecycle and state to be
applied when the task is issued. Use the checkbox to activate the
lifecycle.
14. In the Restrictions tab, select the groups of users and categories of
documents that are applicable to this task template. If the template
applies to all users and documents, leave these options blank.
15. Optionally enter an Initialization / validation script to be run when
starting the workflow.
16. Optionally enter a Script on Save to be executed when a user saves a
task (including issuing):

7 Mar 2016 Page 261


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

17. Click OK.


18. The Add Task Template screen appears. From the drop-down list of
Task Types, select the task type.
19. The Status will be set to Planned as this is a new task. From the
Priority drop-down list, select the priority.
20. To include recipients in the task template, click on the arrow to the
right of the Recipients field. The Specify task recipients screen
appears. Note that there is now a “Group” dropdown under
Recipients, where you can specify a particular group - the user using
the template workflow will only be able to select recipients from
among members of that group.

Alternatively, you can click Automatic and then enter a DQL which
will select the recipients (the query must return user name(s)), for
example
select recipient from reg_table where site_code='${site_code}'

7 Mar 2016 Page 262


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

21. A special case of recipients is Dynamic Recipient, where you can


build a user or group name based on a property and add that:

This is not case sensitive so if the Department name were “Finance”


but the group name is “finance_managers” this will work without a
problem.

Continued on next page

7 Mar 2016 Page 263


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Task Templates, Continued

How to create a 22. From the drop-down, choose All Users and Groups to display all
task template, available users and groups, or All Users or All Groups to display
(cont’d) only those lists. Also choose from a personal distribution list or a
document property. Enter text into the Search Criteria field to filter
the user list.
23. Add users from the user list on the left to the recipients list on the
right using the buttons in the center. Note the choices for adding
group members: All of group or Any of group. Click Save.
24. The Task Properties screen reappears with the selected user(s) added
to the Recipients list.
25. If multiple recipients (either individuals or groups) are chosen, use the
Sequence drop-down list to make the task Parallel (sent to all
recipients simultaneously) or Serial (sent to one recipient or group
after the other, in the order listed on the task).
26. An additional decision is required for Parallel tasks. Should the task
be completed by All recipients or Any one recipient? Make the
appropriate selection from the For Completion By field.

27. Enter a Target Start date and Target Finish date, or complete the
number of days in the Duration field to determine the Target Finish
date.

28. Add Instructions for the task recipient(s), if desired (these will be
added to the notification email). Typically this might not be
necessary on a template workflow.
Continued on next page

7 Mar 2016 Page 264


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Task Templates, Continued

How to create a 29. If the task template is associated with a lifecycle, click the Lifecycle
task template tab to set the lifecycle options. If using the system configuration,
(cont’d) these options may be pre-selected. Otherwise, use the drop-down lists
to select the appropriate lifecycle states when the task is active and
when it is completed.

30. Click the Properties tab to open that screen. Use the Add button to
enter the values to be set by the system on completion. Note that you
can use the Documentum keywords such as date(TODAY), USER
and so on:

7 Mar 2016 Page 265


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Continued on next page

7 Mar 2016 Page 266


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Task Templates, Continued

How to create a NOTE: Allowable values are


task template Any Integer, Double, String
(cont’d) Boolean: t, T, true, TRUE, 1, everything else will be treated as false
Date: TODAY, TOMORROW or date in format yyyy-mm-dd

31. Click on the Scripts tab to open that screen. Enter a script to be
executed on issue, satisfactory or unsatisfactory completion of the
task. The script is a JavaScript-style code where 'object' variable is a
Documentum object and can be used to modify object properties. E.g.
'object.setString("owner_name",
session.getUser(null).getUserName());'. DFC classes as well as Java
classes can be used. Documentum session is available as 'session'
variable.

Continued on next page

7 Mar 2016 Page 267


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Task Templates, Continued

How to create a 32. Click on the Notifications tab to open that screen. These notification
task template settings will be the default for this template. However, users can
(cont’d) modify them when they use the template.

33. To add additional notifications, click Add. The Add task notification
window appears.

Continued on next page

7 Mar 2016 Page 268


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Task Templates, Continued

How to create a 34. From the Notify when task options, choose when the notification will
task template be sent. From the Notify options, choose who to notify.
(cont’d)
35. Select whether to attach no content, the original content, or the PDF
rendition (this will attach the document itself to the email).
36. Use the Reminder check-box to set repeating notifications at the
desired intervals. Click Save to save the notification selections. The
Add task notification window reappears
37. Repeat the previous steps as necessary to add additional notifications.
38. Click the Restrictions tab to open that screen.

39. Check the Restrictions to apply to tasks created with this template.
Users will not be able to modify these settings.
40. Click Add step to add another task step. Follow the previous steps to
define the additional step(s). Use the Remove step button to delete
an individual step.

41. When the task settings are complete, click Save to save the task
template. The template is available for new tasks.

7 Mar 2016 Page 269


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Task Templates, Continued

Modifying task 1. Login to CARA as a user who has Task Template Administrator
template rights, and open the Control Panel, and go to Tasks / Task
properties Templates.
2. The Task screen appears. Select a template to modify and click
Properties:

3. The Template definition screen appears:

7 Mar 2016 Page 270


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

4. Modify details as appropriate and click OK.

Modifying task 1. Login to one of the CARA interfaces (Desktop or Web) as a user
template details who has Task Template Administrator rights, and open the
Control Panel and select Tasks / Task Templates.
2. The Task screen appears. Select a template to modify and click
Modify:

7 Mar 2016 Page 271


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

3. In the Template details screen that appears, modify the 4 tabs of


information (Task Details, Notifications, Lifecycle and
Restrictions) as desired for each task. Click Save at the end.

Deleting a task 1. Ensure you are logged in as a user who has Task Template
template Administrator rights, and open the Control Panel and select Tasks
/ Task Templates.
2. The Task screen appears. Select a template to delete and click
Delete.
3. Click OK to the confirmation:

7 Mar 2016 Page 272


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Periodic Task Definition

What is… Periodic Task


A periodic task is one that will launch automatically after a period of
time. As an example, for an SOP document a periodic task of Review
could be set to launch every year. For this functionality the Periodic Task
job is required to be configured in the docbase.

It is also required to set up Task Templates first to be referenced in the


Periodic Task Definition.

How to… define 1. Open the Control Panel and click on Tasks / Periodic Task
periodic tasks Definitions
2. The Periodic Task dialog appears:

3. To add a definition, click Add.


4. In the task definition dialog that appears, select a document
category for which to apply the periodic task:

7 Mar 2016 Page 273


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

5. Select a task template (which must be created first, see the Task
Templates configuration section above).
6. Select the dates: a number of days before or after a particular date
property of the document.
7. Select if you would like the task to be automatically repeated for
few days by defining a number in the “Repeat every” box. – e.g.
to repeat for 2 days afterwards enter 2 days (e.g. it might fail on
the first day).
8. Finally, select the user as which to start the task (the task will be
as if sent by this user, but the user concerned does not have to
manually intervene in this process). You can also type a document
attribute into the box, as long as it is in angle brackets, eg
<sender>
9. Click Save.

How to… modify 1. Open the Control Panel and click on Tasks / Periodic Task
periodic tasks Definitions
2. The Periodic Task dialog appears. Select an existing definition
and click Edit.
3. Modify the settings as described in the section on creating a
definition above.
4. Click Save.

How to… delete 1. Open the Control Panel and click on General / Periodic Task
periodic tasks Definitions
2. The Periodic Task dialog appears. Select an existing definition
and click Remove.

7 Mar 2016 Page 274


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

3. Click OK to the confirmation.

Please note A docbase job polls the docbase for documents meeting the periodic task
criteria, and then creates a task and issues it. Notifications are sent to the
recipients from the originator specified in the Periodic Task setup.

7 Mar 2016 Page 275


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

CARA Mail Configuration


Mail Configuration

CARA Mail CARA has a built-in email notification mechanism. The steps below are
Notification for setting up which groups get what notifications as well as general mail
Overview server settings and parameters.

Email notification From the CARA Start menu, select the Control Panel and click on the
configuration General / Mail configuration. The following screen appears:

The option to Send emails on behalf of the original user requires that
user’s email account to be set up to allow emails to be sent on their behalf
by the Sender Name account.

The SMTP tab allows entry of SMTP server settings. Enter the Server
details, and select any Encryption and Port number as required.
Optionally, the User Name and the Password field should contain the
login details of the account to be used on the SMTP server for sending.

Continued on next page

7 Mar 2016 Page 276


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Mail Configuration, Continued

Mail queue The mail queue settings are as follows:


settings
- Sender name: the name of the account if no specific sender is
used. This MUST contain an email address (e.g.
CARA System <dmadmin@company.com> or
dmadmin@company.com).
- Max try count: The maximum number of attempts that should be
made to send email notifications
- Resend after seconds: The interval between attempts
- Deletion time unit / deletion interval: The number of times per
unit (day, week, hour) that the mail cleanup job should be run
(cleans up failed email notification queue).

POP/IMAP settings The POP / IMAP configuration allows setting up an email account which
– to receive emails will be polled for emails to import attachments from, into the Staging
for upload to the Area:
Staging Area

- Protocol: POP or IMAP


- Server: The server information, including whether it required SSL
and also the Port number
- User name / password: The user name and password for the
account.

Continued on next page

7 Mar 2016 Page 277


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Mail Configuration, Continued

Notification Each default group can have emails sent in a particular language with a
templates different link (URL). The notification templates themselves are objects in
the docbase which users can add / modify / delete directly (see the next
section). To specify which group gets which notifications, switch to the
notification tab:

- Click Add to add a new notification rule.


- Enter the Templates Folders (name of the folder in the CARA /
Config / Workflow / Notifications folder)
- In the third field (which should be labeled URL) enter the desired
URL to CARA on a particular web server. NOTE: the URL
should end with /index.html or / e.g.
http://localhost:8080/cara/index.html
http://localhost:8080/cara/
- Click Save.

7 Mar 2016 Page 278


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Notification Templates

Change notifications Templates are located in the following location:


(subscriptions)
/System/Applications/CARA3/Config/Mailer/Notifications/

This folder contains template folders inside, to define sets of templates.


By default the product installation installs just one such folder “en”.
Folders can be created as required and then used as the “Templates
folder” in the CARA Mailer Config (Notification templates tab).

There are four change notification templates, which will send


notifications based on the change made by the user to a document:
1. DocumentChange - when the document properties are modified
2. DocumentCheckIn - when thendocument is checked-in
3. DocumentStateChange - when the document is promoted/demoted
4. DocumentPermissionChange - when the document permissions
are modified (using Permissions Dialog only)

The templates can be named with “_<a_status>” e.g. *_Draft to make it


specific to a particular status.

Each template has content (TXT file) which is used as the mail body. The
subject attribute of the template holds the email subject. Both the subject
attribute and the content of the template can contain the following
variables:

1. <link> or <document_link> - a DRL link to the document in


CARA (in an HTML form - <a
href=“.../drl/objectId/...“>.../drl/objectId/...</a>)
2. <link_plain> or <document_link_plain> - a DRL link to the
document in CARA (plain http link)
3. <user_name> - email recipient’s user name
4. <repository> or <docbase> - repository name
5. <attribute> - attribute is any document attribute, e.g.
<r_object_id>, <subject> etc. If an attribute is repeating, the result
values are comma separated
6. If the attribute is a DATETIME attribute, an optional format can
added after a comma, e.g. <attribute,yyyy-MM-dd>
7. Optionally values can be translated based on a dictionary by

7 Mar 2016 Page 279


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

adding <...,aliasName(dictName)> to the template - dictName is


the dictionary name, aliasName is the dictionary alias name, e.g.
<lang,en(Display Labels)>

Continued on next page

7 Mar 2016 Page 280


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Notification Templates, Continued

Task notifications Templates are located in the following folder:


/System/Applications/CARA3/Config/Workflows/Notifications

This folder contains template folders inside, to define sets of templates.


By default the product installation installs just one such folder “en”.
Folders can be created as required and used then as the “Templates
folder” in the CARA Mailer Config (Notification templates tab).

The following templates are used:

1. AcceptedByOtherUser - A notification send to other task recipients


that the task is accepted/processed by another user and that they
therefore do not have to process it.
2. AfterIssued - A reminder of an issued task.
3. Completed (recipient) - A notification of a completed task. Sent to
the task creator.
4. Completed (other) - A notification of a completed task. Sent to an
additional email address.
5. Completed (creator) - A notification of a completed task. Sent to the
task recipient.
6. Delegated - A notification of a task delegation
7. Deleted - A notification of a task deletion
8. FinishDue (creator) - A reminder of a task finishing in X days. Sent
to the task creator.
9. FinishDue (other) - A reminder of a task finishing in X days. Sent to
an additional email address.
10. FinishDue (recipient) - A reminder of a task finishing in X days. Sent
to the task recipient.
11. FinishOverdue (creator) - A reminder for an overdue task. Sent to the
task creator.
12. FinishOverdue (other) - A reminder for an overdue task. Sent to an
additional email address.
13. FinishOverdue (recipient) - A reminder for an overdue task. Sent to
the task recipient.
14. Issued (creator) - A notification of an issued task. Sent to the task
creator.
15. Issued (other) - A notification of an issued task. Sent to an additional

7 Mar 2016 Page 281


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

email address.
16. Issued (recipient) - A notification of an issued task. Sent to the task
recipient.
17. Rejected (creator) - A notification of a rejected task. Sent to the task
creator.
18. Rejected (other) - A notification of a rejected task. Sent to an
additional email address.
19. Rejected (recipient) - A notification of a rejected task. Sent to the
task recipient.
20. StartOverdue (creator) - A reminder of a task not started in time. Sent
to the task creator.
21. StartOverdue (other) - A reminder of a task not started in time. Sent
to an additional email address.
22. StartOverdue (recipient) - A reminder of a task not started in
time. Sent to the task recipient.

Both the subject attribute and the content template can contain the
following variables:

1. <activity.attribute> - attribute is any task attribute (cara_activity


object), if the attribute is repeating, the result values are comma
separated
2. <document.attribute> - attribute is any document attribute, e.g.
<r_object_id>, <subject> etc. If the attribute is repeating, the result
values are comma separated
3. <workflow.attribute> - attribute is any workflow
attribute(cara_workflow object), if the attribute is repeating, the
result values are comma separated
4. <performer> - task action performer (e.g. user completing the task
that initiates the notification)
5. <recipient> - task recipient’s user name
6. <comment> or <comments> - task user comments
7. <instruction> or <instructions> - task instructions - entered on the
task template
8. <all_comments> - all comments entered for the task by all users,
separated by new lines
9. <document_link> - a DRL link to the document in CARA (in an
HTML form - <a href=“.../drl/objectId/...“>.../drl/objectId/...</a>)
10. <document_link_plain> - a DRL link to the document in CARA
(plain http link)

7 Mar 2016 Page 282


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

11. <link> - a link to the Intray or Outray (HTML link)


12. <link_plain> - a link to the Intray or Outray (plain http link)
13. If the attribute is a DATETIME attribute, an optional format can
added after a comma, e.g. <attribute,yyyy-MM-dd>
14. Optionally values can be translated based on a dictionary by adding
<...,aliasName(dictName)> to the template - dictName is the
dictionary name, aliasName is the dictionary alias name, e.g.
<document.lang,en(Display Labels)>

7 Mar 2016 Page 283


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

URL notes

URL additions The CARA URL will take users to the standard CARA Web Desktop
view. However, appending the repository name will preselect that
repository in the list. Alternatively, you can append other information:
http://server:port/cara/#<docbase_name>

http://server:port/cara/#<docbase_name>/
NODE_MY_DESK/NODE_TASKS/NODE_TASKS_IN_TRAY

(and many more like that for Favorites, Recent items etc)

http://server:port/cara/#<docbase_name>/dashboard/<dashboard_name>

http://server:port/cara/#<docbase_name>/explorer

http://server:port/cara/#< docbase_name>/QS/<string> (launches and


executes a quick search)

http://server:port/cara/#<repo>/QS/typeName=<type>&<attr1>=<value1>...
(launches and runs a search with attribute and type values set)

or a variation of that:
http://<host>/cara/#<repository>/QS/typeName=dm_document&object_na
me=Document 1,Document 2

CARA also supports DRLs e.g.


https://<server>/<app>/drl/objectId/0901295280e4f38f
or
http://<server>/<app>/component/drl?objectId=0900042a8004f96a

Some URLs in CARA may also contain the name of the selected view, since e.g.
SnapLists are particular to certain views:

http://<host>/cara/#<repository>%5BDemo%20View%5D/…

Support for DRLs In CARA v3.6+, URLs are generated using the “drl” format, to further
streamline with the existing Documentum DRL format mentioned above.

User Experience in You can encode the required User Experience in the URL by adding the
the URL “ue” parameter as follows:
?ue=MyWidgetSpace or ?ue=Explorer

Continued on next page

7 Mar 2016 Page 284


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

URL notes, Continued

Saving a URL to Once you have navigated to a particular location in CARA (e.g. Favorites
your browser folder, or a particular cabinet / folder or Dimensions node), you can
favorites simply save the URL that is showing as a Favorite in your browser. In
future, when going to the URL, you will be taken back to that same
location (after logging in).

Switching URLs in Note that if you are going to use two different URLs for CARA, you need
the same browser to open a new browser window or restart the browser. This is because the
window applet once opened in a browser window is tied to that URL.

Chronicle ID URLs URLs that reference a Chronicle ID and a specific version are supported:
including version
labels /Content/<repository>/<action>/<i_chronicle_id>:<version_label>
e.g. Content/GlobalDemo/view/090186a180042507:CURRENT
or Content/GlobalDemo/view/090186a180042507:2.0

Execute a custom CARA has the ability to run a Custom Action just after login and the
action after login redirect to a defined URL after.
The URL in the following format: #EXECUTE/repository/custom action
name/redirect URL, e.g. #EXECUTE/cara_dev/Import
file/http:%2F%2Fwww.google.com
NOTE: you can only use a Custom Action that does not require an object
selection.

7 Mar 2016 Page 285


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Administration
Users

What is user CARA provides the functionality to create, modify and delete
management? Documentum user accounts.

How to … manage 1. From the CARA Start menu, select the Control Panel and click on
users Administration / Users

2. In the screen that appears, all the users defined in the docbase are
shown. To filter by name, enter some text in the Starts with field
and click the spyglass button to filter. Click the X to clear.
3. To view which groups a User belongs to, select the user and click
View User Memberships. In the screen that appears, you can select
a group and click Edit to go to the Edit Group function.

7 Mar 2016 Page 286


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

4. Alternatively, simply double-click to open a user definition and


modify the user’s group memberships from there:

Continued on next page

7 Mar 2016 Page 287


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Users, Continued

How to … add a 1. From the User Management screen click Add.


user

2. In the screen that appears, enter at least the mandatory information


(underlined) and other information as required, as follows:

Continued on next page

7 Mar 2016 Page 288


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Users, Continued

How to … add a  State: choose from Active or Inactive


user (cont’d)
 Name: Enter the full user name
 Login name: the Documentum login name
 Login domain: the Documentum login domain
 Source: Choose from None, Inline or LDAP
 Description: a description of the user
 Email Address: user’s email address
 OS Name: user’s Operating System name
 OS Domain: user’s Operating System domain
 Default group: select the default group from the drop-down
 User Membership: add the user to multiple groups
 Default folder: select the default folder using the spyglass icon
and navigating to select the folder
 Privileges: choose from the dropdown of available Documentum
privileges
 Extended privileges: choose from the dropdown of available
Documentum extended privileges
 Client capability: choose from the dropdown of available
Documentum client capabilities
 DB Name: choose a DB name if this user account will be used to
access the database directly
 Workflow disabled: select this option to disable Documentum
workflow (not CARA workflow)
 Turn off authentication failure checking: turn off the default
Documentum authentication failure checking
3. Click Save.
For full details on the meaning of the above, please refer to the
Documentum manual for system administrators.

Continued on next page

7 Mar 2016 Page 289


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Users, Continued

How to … modify a 1. From the User Management screen, select a User and click Edit.
user
2. Edit the user information as defined in Adding a User above, and then
click Save.

How to … delete a 1. From the User Management screen, select a User and click Delete.
user
2. Click Yes to the confirmation screen:

How to … rename 1. From the User Management screen, select a User and click Rename.
a user
2. Enter the new name and click OK:

7 Mar 2016 Page 290


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Groups

What is group CARA provides the functionality to create, modify and delete
management? Documentum groups, as an alternative to working with Documentum
Administrator.

User Groups The following is a description of the groups in CARA:

Group Description
cara_cancel_checkout_managers Members of this group can cancel checkout on other users’
documents without having Superuser access
cara_config_managers Members of this group have access to the CARA
configuration functionality, accessible via the Start /
Configuration / menu in CARA (Tasks, User Capabilities
and View Management)
cara_report_generators Backwards compatibility, no longer used
cara_structure_creators Backwards compatibility, no longer used
cara_task_managers Members of this group can re-assign and delete tasks, can
manage task templates.
cara_template_managers Members of this group can create / modify / delete task
templates.
cara3_users This group is OPTIONAL - but if created, then only users in
this group will be allowed to login through CARA.
CARA_audit_managers Backwards compatibility, no longer used
CARA_config_managers Members of this group have access to the CARA
functionality, accessible via the Start / Configuration /
CARA menu in CARA.
CARA_task_managers Backwards compatibility, no longer used
CARA_template_managers Backwards compatibility, no longer used

Continued on next page

7 Mar 2016 Page 291


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

How to … manage 1. From the CARA Start menu, select the Control Panel and click on
groups Administration / Groups

2. In the screen that appears, all the users defined in the docbase are
shown. To filter by name, enter some text in the Starts with field
and click spyglass button to filter.

Continued on next page

7 Mar 2016 Page 292


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

How to … add a 1. From the Group Management screen click Add.


group

2. In the screen that appears, select “Group” and enter at least the
mandatory information (underlined) and other information as
required, as follows:

Continued on next page

7 Mar 2016 Page 293


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

How to … add a  Name: Enter the full group name


group (cont’d)
 Description: a description of the group
 Email Address: group’s email address
 Owner: select the owner of the group from the drop-down of
available users
 Administrator: select the Administrator of the group from the
drop-down of available users
 Private: is the group private or not
 Dynamic: is the group a dynamic group. If yes, then select:
o Treat users as members; or
o Treat users as non-members
 User members: click the down-arrow and in the screen that
appears, select from the list of available users on the left and move
them to the right to add them to the group.

 Group members: click the down-arrow and in the screen that


appears, select from the list of available groups on the left and
move them to the right to add them to the group.
3. Click Save.
For full details on the meaning of the above, please refer to the
Documentum manual for system administrators.

Continued on next page

7 Mar 2016 Page 294


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Groups, Continued

How to … modify a 1. From the Group Management screen, select a User and click Edit.
group
2. Edit the group information as defined in Adding a Group above, and
then click Save.

How to … delete a 1. From the Group Management screen, select a Group and click Delete.
group
2. Click Yes to the confirmation screen:

7 Mar 2016 Page 295


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Domains

What is domain CARA provides the functionality to create, modify and delete
management? Documentum domains, as an alternative to working with Documentum
Administrator.

How to … manage 1. From the CARA Start menu, select the Control Panel and click on
domains Administration / Groups

2. In the screen that appears, all the users defined in the docbase are
shown. To filter by name, enter some text in the Starts with field
and click spyglass button to filter.

Continued on next page

7 Mar 2016 Page 296


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Domains, Continued

How to … add a 1. From the Group Management screen click Add.


domain

2. In the screen that appears, select “Domain” and enter at least the
mandatory information (underlined) and other information as
required, as follows:

Continued on next page

7 Mar 2016 Page 297


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Domains, Continued

How to … add a  Name: Enter the full domain name


domain (cont’d)
 Description: a description of the domain
 Email Address: domain’s email address
 Owner: select the owner of the domain from the drop-down of
available users
 Administrator: select the Administrator of the domain from the
drop-down of available users
 Private: is the domain private or not
 Dynamic: is the domain dynamic. If yes, then select:
o Treat users as members; or
o Treat users as non-members
 User members: click the down-arrow and in the screen that
appears, select from the list of available users on the left and move
them to the right to add them to the domain.

 Group members: click the down-arrow and in the screen that


appears, select from the list of available groups on the left and
move them to the right to add them to the domain.
4. Click Save.
For full details on the meaning of the above, please refer to the
Documentum manual for system administrators.

7 Mar 2016 Page 298


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Continued on next page

7 Mar 2016 Page 299


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Domains, Continued

How to … modify a 1. From the Group Management screen, select a domain and click Edit.
domain
2. Edit the domain information as defined in Adding a Domain above,
and then click Save.

How to … delete a 1. From the Group Management screen, select a domain and click
domain Delete.
2. Click Yes to the confirmation screen:

7 Mar 2016 Page 300


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Roles

What is role CARA provides the functionality to create, modify and delete
management? Documentum roles, as an alternative to working with Documentum
Administrator.

How to … manage 1. From the CARA Start menu, select the Control Panel and click on
roles Administration / Groups

2. In the screen that appears, all the users defined in the docbase are
shown. To filter by name, enter some text in the Starts with field
and click spyglass button to filter.

Continued on next page

7 Mar 2016 Page 301


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Roles, Continued

How to … add a 1. From the Group Management screen click Add.


role

2. In the screen that appears, select “Role” and enter at least the
mandatory information (underlined) and other information as
required, as follows

Continued on next page

7 Mar 2016 Page 302


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Roles, Continued

How to … add a  Name: Enter the full role name


role (cont’d)
 Description: a description of the role
 Email Address: role’s email address
 Owner: select the owner of the role from the drop-down of
available users
 Administrator: select the Administrator of the role from the drop-
down of available users
 Private: is the role private or not
 Dynamic: is the role dynamic. If yes, then select:
o Treat users as members; or
o Treat users as non-members
 User members: click the down-arrow and in the screen that
appears, select from the list of available users on the left and move
them to the right to add them to the role.

 Group members: click the down-arrow and in the screen that


appears, select from the list of available groups on the left and
move them to the right to add them to the role.
5. Click Save.
For full details on the meaning of the above, please refer to the
Documentum manual for system administrators.

7 Mar 2016 Page 303


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Continued on next page

7 Mar 2016 Page 304


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Roles, Continued

How to … modify a 1. From the Group Management screen, select a role and click Edit.
role
2. Edit the role information as defined in Adding a Role above, and then
click Save.

How to … delete a 1. From the Group Management screen, select a role and click Delete.
role
2. Click Yes to the confirmation screen:

7 Mar 2016 Page 305


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

User Activity Reporting

What is User CARA allows you to quickly report on user activity, showing last login
Activity reporting? and client host IP.

How to … report 1. From the CARA Start menu select the control panel and click on
on User Activity Administration / User Activity

2. In the screen that appears, all the users logins are show, and you can
order the information by any of the columns, as well as Export the
information to Excel.
3. To filter activity from a particular time period, select the appropriate
filter from the dropdown at the top:

7 Mar 2016 Page 306


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

System Lock

What is System You may want to disable access to CARA for all users without bringing
Lock? the system down or making permanent user changes, e.g. for the purposes
of applying system-wide changes.

7 Mar 2016 Page 307


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

How to … apply a 1. From the CARA Start menu select the Control Panel and click
System Lock on Administration / System Lock.
2. In the confirmation screen that appears, click Yes:

3. You are offered the option to enter a lock message, e.g. “The
system is currently unavailable until 9am” or using HTML tags
e.g.: <b>NOTE: </b> The system is unavailable now until 9am
EST:

4. Click OK. You get a confirmation of the successful lock:

Non superuser /sysadmin accounts cannot now connect. Existing


connected users will be locked out at the next logout / timeout.

Continued on next page

7 Mar 2016 Page 308


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

System Lock, Continued

How to … Unlock 5. From the CARA Start menu select the Control Panel and click
the system on Administration / System Lock
6. In the confirmation screen that appears, click Yes:

7. Click OK. You get a confirmation of the successful unlock:

7 Mar 2016 Page 309


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Object Types

What is the Object Administrators can preview all the available Object Types, and for any
Types window? Object Type can access the full details of the type from the same window.

How to … manage 1. From the CARA Start menu select the Control Panel and click
Object Types on Administration / Object Types.
2. The Object Types window will open:

3. If you select a type and click Generate DQL, a window will pop
up showing the full DQL statement required to create the type.
4. The full list of types can be exported to Excel (or CSV or
HTML).
5. You can search for a type using the search box – do not forget to
check the box to Display system types so ensure those are shown
in the list if required.
6. You can open the Details for an Object Type either by
highlighting a type and clicking Details, or by double-clicking on
a type. The Details window will open.

Continued on next page

7 Mar 2016 Page 310


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Object Types, Continued

How to … manage
Object Types
(cont’d)

7. The list of type-specific attributes can be exported to Excel (or


CSV or HTML).
8. To add a new attribute, click Add, and complete the information:

7 Mar 2016 Page 311


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Continued on next page

7 Mar 2016 Page 312


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Object Types, Continued

How to … manage 9. To edit an existing attribute, select it and click Edit and modify
Object Types the information (note, only label changes can be made, or for
(cont’d) string attributes, the length can be extended:
10. To drop an attribute, select it and click Remove.

How to … create To create a new type:


object types
1. Click Add

2. In the screen that appears, enter a Name, Label and Parent type,
and click Save
The type is then created and attributes can be added as described above.

7 Mar 2016 Page 313


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Jobs and Methods

Managing Jobs To manage jobs from within CARA, open the Control Panel, and go to
the Administration tab and click on Job Management.

To work with jobs, right click on a job and select your option:

Run now sets the job to run at the next agent polling interval. View
latest log opens a popup showing the log from the last job run. And
finally, clicking Properties opens the properties of the job for
modification:

Continued on next page

7 Mar 2016 Page 314


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Jobs and Methods, Continued

Managing jobs
(cont’d)

Managing methods On the Job Management screen above, click on the Methods tab, and
again each method can be right-clicked:

Properties will open the method properties for updating:

Continued on next page

7 Mar 2016 Page 315


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Jobs and Methods, Continued

Managing methods
(cont’d)

Custom CARA CARA 3.6 includes a change to the method signature for the invocation
jobs from v3.6 of Documentum Jobs. If any custom jobs where developed against a
prior CARA version these will need to be updated as part of the CARA
3.6 deployment.

The method signature prior to 3.6 was:

execute(ICaraDctmSessionContext context, String


repository, Map parameters, OutputStream os)

The method signature for 3.6 is:

execute(ICaraDctmSessionContext context, String


repository,Map parameters, PrintWriter
printWriter)

Please note that without this modification the job will still run, however,
none of the job processing will be performed and an empty log will be

7 Mar 2016 Page 316


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

created.

Using a CARA To save custom code compilation into methods, you can simply save a
Script to create a CARA Script using the Script Editor, and then create a new script-based
job job using the Jobs Management in CARA. Please refer to the section on
using the Script Editor.

CARA and CARA There are several jobs and methods installed with CARA and CARA that
jobs and methods are used by the system only and should not be changed. However, there
are some which are designed to be configured to run as and when
required. These are listed below.

Job Method
CARA ACL Housekeeper CaraACLHousekeeper
Cleans up unused ACLs (e.g. task ACLs)
Set inactive by default
CARA Auto Promote CaraAutoPromote
Promotes documents through the lifecycle on a
schedule
Set inactive by default
Arguments:
-document_type <r_object_type>
-lifecycle <lifecycle name>
-state <starting status>
-next_state <status to move to>
-date_field <trigger field>
-dql <DQL condition>
-report <true | false>
-docbase <docbasename>
-username <superuser name>
CARA Auto Values Calculation CARA Auto Values Calculation
Recalculates the auto values for documents
which are part of the Qualification argument
Set inactive by default
Arguments:
-qualification <dql from type> dm_document
where a_status = ‘Draft’

7 Mar 2016 Page 317


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Job Method
CARA Mailer CaraMailer
Sends emails based on mail objects (e.g. from
workflow notifications)
Set active by default
Run Mode 1 / Run Interval 5
CARA Mailer Queue Cleaner CARAMailerQueueCleaner
Cleans the mail queue of failed mail objects
Set active by default
Run Mode 3 / Run Interval 1
CARA Orphaned Workflows Cleaner CaraOrphanedWorkflowsCleaner
Deletes orphaned workflows
Set active by default
Run Mode 3 / Run Interval 1
CARA Purge CaraPurge
What category should be removed, when and
how (remove content/remove from vdocs,
audit, notify), final status, final min date, user
selects a date attribute and number of days
when delete it.

The following
1. Category name
2. Date attribute
3. Date interval in days
4. Delete relations
5. Delete annotations
6. Delete vdoc links
7. Delete audit trail entries
CARA Start Periodic Workflows CARAStartPeriodicWorkflows
Starts periodic workflows (advised to set it to
run once a day during the night)
Set active by default
Run Mode 3 / Run Interval 1
CARA Structure Housekeeper CARAStructureHousekeeper3
Cleans up orphaned VD nodes after structures
are deleted
Set inactive by default

7 Mar 2016 Page 318


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Job Method
CARA Workflow Notifications Maintainer CaraWfNotificationsMaintainer
Creates workflow mail objects
Set active by default
Run Mode 3 / Run Interval 1
NOTE: Depending on the version of the CaraQueryExecutor
DocApp / DAR, this job may not exist, and
should be created manually to reference the
method.
CaraQueryExecutor
Executes any query as a method that is required
Set active by default
Run Mode 3 / Run Interval 1
Arguments:
-query <DQL>
e.g.
-query update dm_document objects set
owner_name = ‘dmadmin’ where owner_name
!= ‘dmadmin’
CARACleanTrashDocuments CARACleanTrashDocuments
Permanently removes documents from the com.generiscorp.CARA.jms.
Trash Can CARACleanTrashDocumentsMethod
Set inactive by default
Arguments:
- docbase_name
- cutoff_days (optional, default 14)
- excluded_labels (version labels, separated by
comma)
- exclude (dql qualification)
- delete_now (whether to delete or just check,
T/F)
NOTE: CaraCleanTrashDocumentsMethod will
have no effect if there is no –delete_now T
parameter. Without it, it runs in test mode only

7 Mar 2016 Page 319


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Job Method
CARAMarkVersion3 CARAMarkVersion3
Sets the initial version of a document to the com.generiscorp.CARA.jms.
configured number (0.0, 0.1, 1.0) CARAMarkVersionMethod
Set inactive by default
Arguments:
- docbase_name
- object_id
- version_label
CARARestoreTrash3 CARARestoreTrash3
Restores documents from a user’s Trash com.generiscorp.CARA.jms.
Set inactive by default CARARestoreTrashMethod
Arguments:
- docbase_name
- param_obj_id
CARASecurityLink3 CARASecurityLink3
Calculates security and folder path on saving a com.generiscorp.CARA.jms.
document CARASecurityLinkMethod
Set inactive by default
Arguments:
- docbase_name
- user_name (user login name)
- object_id
- selected_folder_id
CARASecurityLinkUpdate3 CARASecurityLinkUpdate3
Calculates security and folder path on saving a com.generiscorp.CARA.jms.
document CARASecurityLinkUpdateMethod
Set inactive by default
Arguments:
- docbase_name
- qualification (DQL qualification - "SELECT
r_object_id FROM " + qualification)
CARATrash3 CARATrash3
Moves documents to a user’s Trash com.generiscorp.CARA.jms.
Set inactive by default CARATrashMethod
Arguments:
- docbase_name
- param_obj_id
- all_versions (1/0)

7 Mar 2016 Page 320


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Job Method
--- CaraActivityChangeState
Generis CARA method to change state of a
document after an activity completion
--- CaraActivityPostCompletion
Generis CARA method executed after an
activity completion
--- CaraAssignDocument3
Generis CARA method to assign documents in
structures
--- CaraCancelCheckout
Generis CARA method to remove lock from an
object
--- CaraChangeStructurePermissions3
Generis CARA method to change structure
permissions
--- CaraInitializeStructurePermissions3
Generis CARA method to reset structure
permissions on creation
--- CaraInsertStructurePermissions3
Generis CARA method to insert documents in a
structure
--- CaraStructureHousekeeper3
Generis CARA method to clean up orphaned
structures
--- CaraTestMethod
Generis CARA method to test whether the JMS
is running

The following is a list of parameters if calling the jobs independently of CARA:

com.generiscorp.cara.dctm.jms.CaraACLHousekeeper - CARA ACL Housekeeper method.


Removed old, not used ACLs generated by CARA.
- docbase_name
- user_name

com.generiscorp.cara.dctm.jms.CaraActivityChangeStateMethod - CARA Change State method


which promotes or demotes a document on activity completion.

7 Mar 2016 Page 321


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

- docbase_name
- user_name
- object_id
- activity_id
- target_state

com.generiscorp.cara.dctm.jms.CaraActivityPostCompletionMethod - CARA method to run after


activity completion to execute some post-processing.
- docbase_name
- user_name
- object_id
- activity_id

com.generiscorp.cara.dctm.jms.CaraAssignDocumentMethod
- docbase_name
- user_name
- object_id
- parent_node_id
- node_id
- node_containment_id

com.generiscorp.cara.dctm.jms.CaraAutoPromoteMethod - Implementation of CARA Auto Promote


server method.
- docbase_name
- user_name
- document_type
- lifecycle
- state
-next_state
-date_field
-dql
-report

com.generiscorp.cara.dctm.jms.CaraCancelCheckoutMethod - CARA method to cancel checkout on


a document.
- docbase_name
- user_name
- object_id

com.generiscorp.cara.dctm.jms.CaraChangeStructurePermissionsMethod - This server method


sets/changes structure permissions. Coordinators with WRITE, Contributors with RELATE and
Consumers with READ.
- docbase_name
- user_name
- node_id
- coordinators

7 Mar 2016 Page 322


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

- contributors
- consumers

com.generiscorp.cara.dctm.jms.CaraInitializeStructurePermissionsMethod - This server method


initializes structure permissions using a template ACL
- docbase_name
- user_name
- node_id
- source_acl_id
- creator

com.generiscorp.cara.dctm.jms.CaraInsertStructurePermissionsMethod - This server method


modifies structure permissions after a second structure is inserted/included.
- docbase_name
- user_name
- parent_id_list
- inserted_id
- retain_permissions

com.generiscorp.cara.dctm.jms.CaraMailerMethod - CARA Mailer method. Sends email notification


based on cara_mail_message objects.
- docbase_name
- user_name

com.generiscorp.cara.dctm.jms.CaraMailerQueueCleanerMethod - CARA Mailer Queue Cleaner


method. Cleans the old cara_mail_message objects.
- docbase_name
- user_name

com.generiscorp.cara.dctm.jms.CaraMaintainWorkflowOverdueNotifications - CARA method to


maintain workflow overdue notifications. It generates mail notifications when needed.
- docbase_name
- user_name

com.generiscorp.cara.dctm.jms.CaraNotStartedWorkflowsCleanerMethod - CARA method to delete


the workflows not started by the due date.- docbase_name
- user_name

com.generiscorp.cara.dctm.jms.CaraOrphanedWorkflowsCleanerMethod - CARA Method to


remove all orphaned workflows (when doc is deleted)
- docbase_name
- user_name

7 Mar 2016 Page 323


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

com.generiscorp.cara.dctm.jms.CaraQueryExecutorMethod - CARA method to execute a DQL -


works only run from a job. To e.g. delete periodically some objects
- docbase_name
- user_name
- query

com.generiscorp.cara.dctm.jms.CaraStartPeriodicWorkflows - CARA method to start periodic


workflows.
- docbase_name
- user_name
- report_to (email)

com.generiscorp.cara.dctm.jms.CaraStructureHousekeeperMethod - CARA JMS Method to deletes


disused CARA structure nodes and context objects.
- docbase_name
- user_name

com.generiscorp.cara.dctm.jms.CaraTestMethod - A test method which is invoked to verify whether


the JMS is up and running
- docbase_name
- user_name

com.generiscorp.CARA.jms.CARACleanTrashDocumentsMethod
- docbase_name
- cutoff_days (optional, default 14)
- excluded_labels (version labels, separated by comma)
- exclude (dql qualification)
- delete_now (whether to delete or just check, T/F)

com.generiscorp.CARA.jms.CARAMarkVersionMethod
- docbase_name
- object_id
- version_label

com.generiscorp.CARA.jms.CARARestoreTrashMethod
- docbase_name
- param_obj_id

com.generiscorp.CARA.jms.CARASecurityLinkMethod
- docbase_name
- user_name (user login name)
- object_id
- selected_folder_id

7 Mar 2016 Page 324


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

com.generiscorp.CARA.jms. CARASecurityLinkUpdateMethod
- docbase_name
- qualification (DQL qualification - "SELECT r_object_id FROM " + qualification)

com.generiscorp.CARA.jms.CARATrashMethod
- docbase_name
- param_obj_id
- all_versions (1/0)

Reviewing debug logs


When a job has run, either manually or automatically, you can find the debug log files of the job in
the Temp folder, under a folder with the same name as the job.

7 Mar 2016 Page 325


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Log Files – Viewing from CARA

How to set up the In the cara.xml file on the application server, define the name and path to
log file viewing one or more log files (application server, docbase, JMS) as follows, then
from within CARA restart the application server:

<!-- Log files accessible from CARA via Control Panel / Administration /
Logs -->
<!-- <logFiles>
<file name="Tomcat log">c:/Program Files/Apache
Software Foundation/Tomcat 6.0/logs/catalina.out</file>
</logFiles>-->

The log files then appear in the Control panel / Administration / Logs:

7 Mar 2016 Page 326


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

User Preferences

How the User When a user first logs into the system, if they do not have an existing
Preferences work User Preferences object, CARA will create one by copying the default
User Preferences object as follows:
 Single default user preferences
 Default user preferences for the user’s default group

This means that if you want to preset various settings, you can either
update the default objects (or create defaults per default group) or you can
actually create that user’s preferences object and set various values.

Once the user preferences are created, you can update user preference
objects through DQL to set new preferences (or simply delete them and
have the system recreate new ones).

Default user The default preferences are those of object type “cara_user_preferences”.
preferences NOTE: there are no preferences object installed with CARA. If you want
to create and pre-configure preferences, create objects of this type called:
 Default Used if user’s default group does not have a
specific preference
 <group name> If user’s default group has this name, this is
used

The attributes, together with those for individual user preferences, are
shown on the following pages.

NOTE: Once a user logs in, an individual object of type


“cara_user_preferences” is created for them, either hard-coded (if no
cara_preferences objects exist) or by copying the setting on the
appropriate cara_preferences object above.

7 Mar 2016 Page 327


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

User Preferences - attributes


CARA_PREFERENCES

Attribute Name Type Length Repeating Description

restrict_cabinets Boolean 0 Is Cabinet restrictions is being


used

cabinet_label String 2 Select cabinet label (if additional


labels are being used in Cabinet
restrictions)

cabinet_name String 255 Yes Name of the cabinets selected


to view (if Cabinet restrictions is
being used)

show_binding Boolean 0 Should binding information be


shown

vd_column_name String 32 Yes Columns selected to display in


Virtual Documents window

vd_column_width Integer 0 Yes Width of columns selected to


display in Virtual Document
window

structure_column_name String 32 Yes Columns selected to display in


Structure view

structure_column_width Integer 0 Yes Width of columns selected to


display in Structure view

docbase_column_name String 32 Yes Columns selected to display in


docbase view

docbase_column_width Integer 0 Yes Width of columns selected to


display in docbase view

7 Mar 2016 Page 328


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

CARA_USER PREFERENCES

Attribute Name Type Length Repeating Description

user_name String 64 Name of the user for whom it


is the preferences

subscription_id ID 16 Yes Object ID of all the objects to


which the user has
subscribed (through adding to
the CARA Favorites folder,
and selecting to be notified of
changes)

skip_read_access_warning Boolean 0 Whether to present the


warning on accessing read-
only content that it cannot be
modified

delegate_tasks_to String 32 Person to whom tasks should


be delegated (Out of Office)

reporter_query String 1024 Yes Last executed query, which


displays what is in the search
results node

cabinets_restricted Boolean 0 Is Cabinet Restriction


switched on

restricted_cabinet_id ID 16 Yes IDs of all cabinets selected if


Cabinet Restriction is
switched on

cabinet_display_attr_index Integer 0 Which cabinet display label to


use (if Cabinet Restrictions is
being used)

recent_item_id ID 16 Yes Object IDs of the most


recently accessed items (up
to 20)

view_name String 255 Name of the Document View


last selected

view_portlet String 64 Yes Widgets being displayed

favourite_id ID 16 Yes Object ID of all the objects


which the user has added to
the CARA Favorites folder

7 Mar 2016 Page 329


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Actions
Overview

What are… Custom Actions allow you to add any customization you want to CARA,
Custom Actions and configure it to appear as a menu or button in the application. This
avoids you having to actually customize the CARA application code, thus
ensuring that future upgrades of product versions are not impacted by
your customizations and vice versa.

The types of custom actions available are:

 Open dialog with a URL

 Execute DQL Query

 Execute Search DQL

 Exexute an API Script

 Execute Server Method

 Execute Script

 Open Dashboard Report

 Call a RESTful Web Service

7 Mar 2016 Page 330


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Defining a Custom Action

Adding a Custom From the CARA Start menu, select the Control Panel and click on
Action General / Custom Actions.

1. In the screen that appears, click Add or select an existing one and click
Duplicate:

2. Complete the definition using the tabs as defined below, and click OK.
Then click Save to the Custom Actions screen.

Removing a From the CARA Start menu, select the Control Panel and click on
Custom Action General / Custom Actions.

1. Select the Custom Action and click Remove.


2. Click Save to the Custom Actions screen.

Editing a Custom From the CARA Start menu, select the Control Panel and click on
Action General / Custom Actions.

1. In the screen that appears, select the Custom Action and click Edit.
2. Complete the definition using the tabs as defined below, and click OK.
Then click Save to the Custom Actions screen.

7 Mar 2016 Page 331


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Actions – General Tab

General Tab On the General tab, you define the following:

Standard Action: Choose an existing action to replace. Replacing Documentum workflow


actions will do the custom action as well as the existing action (e.g. Finish
Task will also finish the task as well as whatever is defined as custom).
You will also get a choice of choosing this replacement only for certain
processes / activities.
Name: An internal name for the action, for reference only
Description: An internal description for the action, for reference only. Click the search
icon to open a larger screen for text input.
Label: The label which will be used in the menus. This can include selecting a
label from the dropdown of the Display Labels dictionary for multi-lingual
aliasing
Toolbar Label: The label which will be used in the Toolbar. This can include selecting a
label from the dropdown of the Display Labels dictionary for multi-lingual
aliasing.
Icon: Select an icon from the dropdown for use on the Toolbar.
Main menu location: If desired, the Custom Action can be added to the main Tools, Tasks, or
Settings menus; then it will appear in all views
Display on Desktop: For an action that does not select a document, you can add the icon to the
CARA Desktop

7 Mar 2016 Page 332


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Actions – Definition Tab

Definition Tab On the Definition tab, you define the type of custom action. Select from:
 Action Group
 Open dialog with a URL
 Execute DQL Query
 Execute Search DQL
 Exexute an API Script
 Execute Server Method
 Execute Script
 Open Dashboard Report
 Call a RESTful Web Service
The variable ${r_object_id_list} is available for executing Custom
Actions on multiple documents in a single transaction with the
following action types. Otherwise using just r_object_id will have the
action run multiple times, one for each ID:
1. Server method - simple list separated by comma
2. Custom Dialog with URL - simple list separated by comma
3. DQL - escaped list of IDs, e.g. '000000','11111', '2222'
When r_object_id_list variable is used, document attributes variable are
not replaced as there might be more than one document selected.
Custom Actions that are built as a Documentum task action replacement –
there is now the ability ability to use document attributes that is attached
to the workflow, e.g.

7 Mar 2016 Page 333


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

DQL Query:

Select whether the DQL should be executed as a superuser. In the DQL


field enter the DQL query to execute. The syntax ${var} can be used,
where 'var' can be one of the following and is extracted at runtime:
 'user_name'
 'repository'
 an action variable name
 a property of the selected object.

Execute Search DQL:


This allows you to specify a DQL query to execute, the results of which
will be displayed on the Search node of CARA. The DQL must return
r_object_id in the first column. The ${var} syntax can be used, where
'var' is 'user_name', 'repository', an action variable name or the selected
object property.

7 Mar 2016 Page 334


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

The value is extracted at runtime:


 'user_name'
 'repository'
 an action variable name
 a property of the selected object.
In Custom Action DQL (type=Execute DQL or Execute Search) it is
possible to use [] brackets as a conditional part of DQL.
e.g. select a from b where c='a' [and d='${var}']
when var is null or empty, the whole DQL part in brackets will be
removed, if not, then just brackets will be removed

7 Mar 2016 Page 335


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Open a Dialog with a URL

In the URL field enter the URL to include in a dialog (iframe). The
syntax ${var} can be used, where 'var' can be
 'user_name'
 'repository'
 an action variable name
 a property of the selected object.
 ${ticket}
The value is extracted at runtime.
The Dialog type option allows you to choose whether to open the dialog
as an Internal window in CARA, or as an External browser tab /
window.
Specify also the Dialog height and dialog width (both in pixels, leaving
it blank leaves the application default).
Choose the Dialog buttons to display (OK, Save, Close, Cancel, X).
If the option 'Save and Cancel' is selected, the JavaScript method
'saveDialogData()' is called on clicking the 'Save' button, or the
JavaScript method 'cancelDialogData()' is called on clicking the 'Cancel'.
The dialog is closed if the method 'canDialogBeClosed()' returns TRUE.

7 Mar 2016 Page 336


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Execute an API Script

Select whether to execute the API as a superuser. In the API script


field enter the API script to execute. The syntax ${var} can be used,
where 'var' can be
 'user_name'
 'repository'
 an action variable name
 a property of the selected object.
You can also use '@{last_result}' to get the previous command execution
result.

Execute a Server Method

7 Mar 2016 Page 337


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

In the Method Name field enter the name of the Documentum method to
be called.
In the Method Parameters field enter the parameters to be passed to the
method. The syntax ${var} can be used, where 'var' can be
 'user_name'
 'repository'
 'password'
 an action variable name
 a property of the selected object.
The value is extracted at runtime.

Execute Script

7 Mar 2016 Page 338


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Select whether to execute the Script as a superuser. In the Script field


enter the Script to execute.
 The ‘objects’ variable is a list of the selected Object IDs.
 DFC classes as well as Java classes can be used.
 – sessionContext and – username are also available.
NOTE: if the script is set to require one or more files, the user will be
prompted to import / select the files as part of the custom action. The
Allowed formats allows definition of file formats allowed e.g. .zip. If
empty, all formats are allowed.

The following events allow using multiple IDs in the following actions,
concatenated by a comma e.g.
custom/example.jsp?repository=${repository}&objectId=<id>,<id2>:
1. Open document properties
2. View
3. Print§
4. Print for

Open Dashboard Report

7 Mar 2016 Page 339


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Define which Dashboard and Report to open.

Create an Action Group


An Action Group is a set of custom actions that will be grouped into a
submenu or a dropdown from a button:

Or

Define this as normal on the General tab, and on the Definitions tab select
the custom actions that you wish to appear in the group:

7 Mar 2016 Page 340


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Call a RESTful Web Service

In the URL field enter the Web Service URL to call using the GET
method. The syntax ${var} can be used, where 'var' can be
 'user_name'
 'repository'
 'password'
 a property of the selected object.
The value is extracted at runtime.

Building your own GWT screen


The steps below are for building a custom action screen using
GWT/GXT:
a. Create a Custom Action to “Open dialog with a URL” and define
the path to the URL (e.g. in the Custom folder of the CARA app)

7 Mar 2016 Page 341


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

b. Create and deploy the GWT project to the server with the URL
specified. Note: Server side code can extend from
AbstractCaraServiceServlet to get the IDfSession there - this is the
key element.
c. The GWT cache will be organized under the “custom” folder of
the CARA app.

Importing content as part of a Custom Action


To import a single file use the following Script (modify as required) and
set “Required Files” to Single (use Multiple to allow import of multiple):
importPackage(com.generiscorp.cara.dctm.api.utils)
for (var i = 0; i < files.size(); i++) {
var object = session.newObject("dm_document");
object.setObjectName(files.get(i).getFileName());
object.link("/Temp");

object.setContentType(CaraFileFormatDetector.detectFor
mat(files.get(i).getFileName(), session));
object.setFile(files.get(i).getFilePath());
object.save();
}

7 Mar 2016 Page 342


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

7 Mar 2016 Page 343


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Actions – Variables Tab

Variables Tab On the Variables tab, you define the variables to be used for a custom
action:

To add a variable, click Add. Enter the information on the popup screen:

Name: A unique name for the variable


Label A label or description for the variable

7 Mar 2016 Page 344


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Type: Variable type e.g. Boolean, String


Repeating: Whether the variable supports multiple values or not
Source: If the action will only be performed on one object, the
value of this attribute will be copied as the default value
of the variable.
Default value: The default value for the variable
To modify existing variables, select them and click Edit, and complete
the information above. To remove variables, select them and click
Remove.
You can also define a form for the variables. This form will be presented
to users to collect variables to enter into the custom action processing.
Click the Edit Form button, and then proceed with the configuration using
the same steps as for the Properties configuration (see that chapter in this
guide).
The Custom Save Button Label allows you to specify a string to use for
the Save button (in the place of the word Save) including selecting from
the multi-lingual Display Labels dictionary.
In the Variables initialization script section, you can enter a script that
will allow you to initialize any variables that will appear on the form.
Available variables: Documentum session as 'session', action variables as
'variables', selected objects as 'object' or 'objects'. E.g.
variables.set("effective_date", new java.util.Date());

7 Mar 2016 Page 345


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Actions – Restrictions Tab

Restrictions Tab On the Restrictions tab, you can define restrictions for the custom action:
Group Restrictions: Which groups have permission to access
this Custom Action. If blank, then all users
have permission.
Required object selection: Whether the action can be triggered with no
object selected, or it requires one or
one/more objects selected
Audit Event: Event used to audit the action. Categories /
Audit Event configuration applies.
Type: What object type, if any, the object(s) must

7 Mar 2016 Page 346


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

be to perform the Custom Action


Required Permission: If the action requires an object selection,
whether there is a minimum permission the
user has to have on the object before being
able to perform the custom action.
Extended Permission: What level of extended permissions, if any,
are required for the user on selection of
object(s) to perform the Custom Action.

Enable advanced
conditions

If the function should be made available only depending on conditions,


you can set which conditions have to be met. Select first whether All,
Any, or a Custom combination of settings should be enforce (custom
allows you to choose multiple and decide on the AND / OR between
them). Then select whether, based on these, to Enable or Disable the
Custom Action.

Then click Add to add a condition:

If selecting Document property, select the property from the dropdown


and click Next. In the next screen, enter the conditional values (the
options will depend on the property type) and click Save

7 Mar 2016 Page 347


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

If selecting a folder path, click Next and enter the values:

If selecting a User Name or Group Name, click Next. Enter the


user/group condition and click Save:

Add other conditions as appropriate.

7 Mar 2016 Page 348


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Actions – Options Tab

Options Tab On the Options tab, you define the messaging for a custom action:

You can formulate a question to ask the user before execution, and a
confirmation to present to the user after the action is executed. You can
also define a message for when the Custom Action fails to execute (which
will override any default system message e.g. DFC error or stacktrace
etc).
For both, you can use the syntax ${attribute} where attribute is an
attribute name on the selected object(s).

You can also use a variable that is defined on the Custom Action.

Finally, you can also use multi-lingual values from the Display Labels
dictionary.

7 Mar 2016 Page 349


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Actions – Completion Tab

Completion Tab On the Completion tab, you define the list of options to execute at the end
of a custom action:

Open Properties – opens the properties for the ID variable specified:

View - opens the object for Viewing for the ID variable specified

View PDF - opens the object for Viewing PDF for the ID variable
specified

Export – starts the export process for the ID variable specified

Print - starts the print process for the ID variable specified

7 Mar 2016 Page 350


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Controlled Print - starts the controlled print process for the ID variable
and the Print For variable specified

Locate – opens the tree down to the folder containing the object with the
ID variable specified

Open Folder Path – Updates the Details pane to display the folder path
specified in the Path variable

Expand Folder Path – Open the tree view to display the folder path
specified in the Path variable

Open as Search Result – displays the object with the ID variable as a


search result

7 Mar 2016 Page 351


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Actions – Export / Import

Exporting or To export a Custom Action, select it and click Export. Choose where to
Importing Custom save the XML file:
Actions

To import a Custom Action, click Import, select the Custom Action XML
file and import that.

7 Mar 2016 Page 352


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Actions – Execute as Superuser

Execute as So far all the Custom Actions with "Execute as super user" were executed
superuser – on the JMS server when user executing it was not a super user. Thus the
validation script could not contain a "thrown" syntax.
messages
There is a new option added in v3.8.2, so the action can be still executed
on the Application Server instead of JMS and because of that the script
can still throw a message to a user.
It requires configuring the super user name and password in
repositories.properties file as below - password must be encrypted. If not
configured, it will work as it used to - on JMS server.
That change is required to simplify the development and debug process
and allow throwing a message from any kind of script.

repository.name[0]=cara_dev
repository.label[0]=CARA
repository.superuser.name[0]=dmadmin
repository.superuser.password[0]=cFb/WZhM4HMvICSq/2cJpQ==

7 Mar 2016 Page 353


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Actions – Execute after Login

Execute a custom CARA has the ability to run a Custom Action just after login and the
action after login redirect to a defined URL after.
The URL in the following format: #EXECUTE/repository/custom action
name/redirect URL, e.g. #EXECUTE/cara_dev/Import
file/http:%2F%2Fwww.google.com
NOTE: you can only use a Custom Action that does not require an object
selection.

7 Mar 2016 Page 354


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Customizing CARA
Replacing classes

Customizing more In 3.5.3 only some classes can customized and only in the webapp, not in
than through the JMS application. From 3.6 all CARA classes and operations can be
Custom Actions or customized in the following way:
Scripts

1. Create a custom JAR with a custom class


2. The class must be located in the following package or any
subpackage: com.generiscorp.cara.dctm.api.custom
3. The class must extend the CARA class
4. The class must have two annotations: @Component @Primary
5. The created JAR must be added into cara.war/WEB-INF/lib and
into the JMS application if needed

Example:

@Component
@Primary
public class CustomCaraContentResolver extends CaraContentResolver {

@Override
public CaraContentLink getContentLink(CaraContentRequest contentRequest,
Map<String, String> initParams, ICaraDctmSessionContext context, String repository)
throws CaraException {
//TODO custom processing or
return suprt.getContentLink(...);
}
}

OR

@Component
@Primary
public class CustomCheckOutOperation extends CheckOutOperation {
@Override
protected void doValidate() throws CaraValidationException, CaraException {
throw new CaraValidationException("Custom check-out not allowed!");
}
}

7 Mar 2016 Page 355


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Documentum In v3.6.1 upwards, there is a new method to extend:


workflow method
to extend @Override
public List getProcesses(List objectIds, ICaraDctmSessionContext
context, String repository) throws CaraException;

7 Mar 2016 Page 356


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Customizing the applet

Customizing the It is possible to customize the applet, e.g. to have a button added that will
applet automatically load all documents from a particular “watched” folder into
the applet when clicked. To do this, edit the filedialog.jsp, e.g. as shown
below:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"


"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
<script type="text/javascript" src="../js/deployJava.js"></script>
<style>
applet,object {left: 0px; top: 0px; overflow: none}
body {padding:0px; margin:0px; border:0px; overflow: none}
</style>
</head>
<body>
<script>if (deployJava.versionCheck("1.6+") == true)
deployJava.runApplet({codebase:'../applets/', archive:'outldd-2.0.3.jar,dnd-applet-
2.0.28.jar', code:'DnDApplet.class', style:'position: absolute; width:100%;height:145px',
id:'DnDApplet'}, {labelFileName: '<%=request.getParameter("labelFileName")%>',
labelFormat: '<%=request.getParameter("labelFormat")%>', singleFile:
'<%=request.getParameter("singleFile")%>', hideFormat: 'false'}, '1.5');</script>
<button type="button" style="position: absolute; top: 147px; width:100%;'"
onclick="document.getElementById('DnDApplet').addFilesFromFolder('c:/Users/Mariu
sz Pala/Desktop/Test Docs')">Add files from local folder</button>
</body>
</html>

7 Mar 2016 Page 357


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Search configuration
Asynchronous settings

Asynchronous For asynchronous searching make sure you have at least DFC 5.3 both on
searching content server and host machine. Sometimes, the server settings will
prevent the same number of results for asynchronous and synchronous
searching. If this happens go to the dfc.properties both on content server
and web server host and add/adjust:

# Maximum number of results to retrieve by a query search.


#
dfc.search.maxresults=1000

# Maximum number of results to retrieve per source by a


query search.
#
dfc.search.maxresults_per_source=350

Additionally here are other important parameters that might be adjusted:

dfc.search.ecis.enable=true

# Time in milliseconds to wait for answer from ECIS server.


#
dfc.search.ecis.access.timeout=180000

# Time in milliseconds between refreshes of the search


source map cache.
#
dfc.search.sourcecache.timeout=1200000

# Time in milliseconds between refreshes of the cache of


docbase formats.
#
dfc.search.formatcache.timeout=1200000

# Time in milliseconds between refreshes of the cache of


type information.
#
dfc.search.typecache.timeout=1200000

7 Mar 2016 Page 358


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Scripts, DQL and API


Using the API Command Feature

How to run an API 1. From the Tools menu, select API or click the API tool or from the
search CARA Start menu select API or click on the API icon on the CARA
Desktop.
2. The API window appears.

3. Enter the API command and click Execute.


4. The results are displayed in the Result window.

7 Mar 2016 Page 359


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Using the DQL Screen

How to run a DQL 1. From the Tools menu, select DQL or click the DQL tool or from the
search CARA Start menu select DQL or click on the DQL icon on the
CARA Desktop.
2. The DQL window appears.

3. Enter the query and click Execute.


NOTE: if you highlight just a part of the statement, only that part will
be executed – without highlight the whole statement is run.
4. The results are displayed in the Result window.

Please note Only system administrators can run DQLs other than “select” statements.
You can right-click on any field in the search results and Copy to
Clipboard.
If you open the DQL window from the menu inside a CARA window,
and use a “select* from” DQL, right-clicking on the object ID will also
offer you a Locate option which navigates to and displays the document.

7 Mar 2016 Page 360


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Working with DQL Results

How to manage DQL search results appear in the lower section of the DQL search
data in the DQL window.
Search Results
window

Use the buttons within the result window to export to Excel or display in
chart format.

Please note If you open the DQL from inside the CARA Explorer window (ie using
the menu, not the desktop icon) then right-clicking on an object will gives
you an additional menu item of Locate, which will navigate to the (first)
folder to which the result is linked.

7 Mar 2016 Page 361


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Saving DQL Searches

How to save a DQL DQL searches are saved automatically in a “most recently used”
search dropdown of Saved queries.

How to re-run a 1. Open the DQL window.


saved DQL search
2. Use the drop-down list to display the available saved queries.

3. Highlight the appropriate query and click Execute.

How to delete a 1. Open the DQL window.


saved DQL search
2. Use the drop-down list to display the available saved queries.

3. Highlight the appropriate query and click Remove saved query.

7 Mar 2016 Page 362


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Functions executed from custom screens

Functions You can call CARA actions from a custom JSP or form page, using the
executed from following (there are examples of each in the file …/custom/example.jsp
custom screens that is delivered with the CARA installation).

In a custom JSP/HTML the cara.js file can be included to allow


interaction with CARA UI.

<script type="text/javascript" src="cara.js"></script>

The list and description of available functions is documented in the cara.js file:
/**
* CARA Integration scripts allowing interaction with CARA UI.
*/
/**
* Open a document properties dialog
*/
function caraOpenProperties(repository, objectId) {
window.parent.caraOpenProperties(repository, objectId);
}
/**
* Downloads and opens a document for viewing
*/
function caraView(repository, objectId) {
window.parent.caraView(repository, objectId);
}

/**
* Downloads and opens a document for viewing (by folder path)
*/
function caraViewByPath(repository, path) {
window.parent.caraViewByPath(repository, path);
}

/**
* Downloads and opens a document PDF rendition for viewing
*/
function caraViewPDF(repository, objectId) {
window.parent.caraViewPDF(repository, objectId);
}

/**
* Opens a document preview dialog
*/
function caraPreview(repository, objectId) {
window.parent.caraPreview(repository, objectId);
}

/**
* Expands the folder path in the navigation tree
*/

7 Mar 2016 Page 363


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

function caraExpandFolderPath(repository, path) {


window.parent.caraExpandFolderPath(repository, path);
}

/**
* Opens the selected folder path in the content panel
*/
function caraOpenFolderPath(repository, path) {
window.parent.caraOpenFolderPath(repository, path);
}

/**
* Locates the selected documens and opens in in the content panel. If
expandAlsoFolderPath equals true, then also nagivation tree is expanded
*/
function caraLocate(repository, objectId, expandAlsoFolderPath) {
window.parent.caraLocate(repository, objectId, expandAlsoFolderPath);
}

/**
* Sets the selected document as a search results and opens the Search Results node.
*/
function caraOpenObjectAsSearchResult(repository, objectId) {
window.parent.caraOpenObjectAsSearchResult(repository, objectId);
}

/**
* Runs a quick search for a document
*/
function caraQuickSearchDocuments(repository, searchString) {
window.parent.caraQuickSearchDocuments(repository, searchString);
}

/**
* Runs a quick search for a folder
*/
function caraQuickSearchFolders(repository, searchString) {
window.parent.caraQuickSearchFolders(repository, searchString);
}

7 Mar 2016 Page 364


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Script Editor

Script Editor The Script Editor allows you to enter a script and test it for correctness:

Please note that the Documentum session is available as the variable


'session'. To execute category/classification scripts the 'object' variable
need to be initilized at the beginning, e.g.

var object = session.getObject(DfUtil.toId("0900000000000000"));

NOTE: if you select a document prior to opening the Scripts Editor, then
the document will show in the top dropdown and then you do NOT
require the line above as CARA will substitute the ID as the variable
“object” into the script.

7 Mar 2016 Page 365


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Saving scripts Once you have entered a script, you can click Save script as to save it.
This will save the script as an object of type xxxxxxx in the folder /
System / Applications / CARA3 / Config / Scripts.

The script will be available from there to open in the Saved Scripts
dropdown, or to call from the method CaraExecuteScript (see the section
on customization on page 361).

7 Mar 2016 Page 366


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Running Scripts as Jobs

Scripts – run as If you write a CARA Script, you can have it executed periodically as a
job job. To do this:

1. Write a script using the Scripts Editor in CARA, and save it


2. In the Job Management screen click Add Script Job, and select the
script:

3. You will then configure the job, there the Method Name and
arguments have been set:

You can write custom messages into the job log using the syntax:

method.log("message");

Where “message” can be / include variables.

7 Mar 2016 Page 367


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Script Examples

Script examples The following are some examples of custom scripting that can be used, in
order to give an idea of how to approach the scripting.

Overview Script language: JavaScript / Rhino

Available variables for pre-initialization script:

1. session - Documentum session (IDfSession)


2. sessionContext - CARA session context
3. repository - Documentum repository (String)
4. userName - User executing the script
5. model - references the POJO used to create a document. Attributes can
be set usin model.set("attr",value);
6. folderId - selected folder ID (IDfId)
7. template - selected template/object to copy (IDfSysObject)
8. inheritanceSourceId - selected document ID (IDfId)
9. documentType - Document type (enum
com.generiscorp.cara.model.classification.CaraDocumentType.Type:
PLACEHOLDER, BLANK_DOCUMENT, MODEL_DOCUMENT,
COPY_DOCUMENT, IMPORT_FROM_FILESYSTEM, BLANK_STRUCTURE,
MODEL_STRUCTURE, COPY_STRUCTURE)

Available variables for post-initialization script:

1. session - Documentum session (IDfSession)


2. sessionContext - CARA session context
3. repository - Documentum repository (String)
4. userName - User executing the script
5. isNew - whether this is new object (boolean)
6. object - created object (IDfSysObject)
7. template - selected template/object to copy (IDfSysObject)
8. checkInVersion - selected checkin version (integer: 0 - major, 1 - minor,
2 - same)

Available variables for custom action script:

1. session - Documentum session (IDfSession)


2. sessionContext - CARA session context
3. repository - Documentum repository (String)
4. userName - User executing the script
5. objects - selected objects (ArrayList of IDfSysObject)
6. object - selected object (IDfSysObject)

7 Mar 2016 Page 368


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

7. variables - references the POJO with variables, values can be accessed


with variables.get("variable_name"), in case of repeating values it
returns ArrayList
8. operationFactory - CARA operation factory
9. configFactory - CARA config factory

e.g.

1. State change

var op =
operationFactory.getOperation(com.generiscorp.cara.dctm.api
.operations.ChangeStateOperation, sessionContext,
repository);
op.setTargetState("Sent");
for (var i = 0; i < objects.size();i++) {
var obj = objects.get(i);
op.add(obj.getObjectId().getId());
}
op.execute();

2. Category validation

var categoryConfig =
configFactory.getCategoryConfig(session);
if
(com.generiscorp.cara.dctm.api.utils.CaraDocumentCategoryVa
lidator.isValidForObject(object,categoryConfig.findCategory
(“Category Name”))) {
//some category based processing
}

Continued on next page

7 Mar 2016 Page 369


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Script Examples, Continued

JSP page – String repository = request.getParameter("repository");


Custom Actions –
code to get a ICaraDctmSessionContext context =
session DctmSessionContextFactory.getSessionContext(request);
IDfSession dfSession = null;
try {
dfSession = context.getSession(repository);
..........
} finally {
if (dfSession != null) {
context.releaseSession(dfSession);
}
}

Classification This is an example of the kind of script you can use for Classification
Initialization script initialization - this will be executed on a document that is being created
before the user gets to the properties screen, and therefore populate
something in that screen. In this case, it populates the user's email
address from their dm_user profile into the title attribute.

var query = new DfQuery("select user_address from dm_user where user_name


= USER");
var coll = null;
try {
coll = query.execute(session, 0);
if (coll.next()) {
model.set("title", coll.getString("user_address"));
model.addModifiedProperty("title");
}
} finally {
if (coll!=null) {
coll.close();
}
}

Continued on next page

7 Mar 2016 Page 370


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Script Examples, Continued

Classification This is an example of the kind of script you can use for Classification
Post-Processing post-processing - this will be executed on a document that is being
script created after the user clicks Save on the properties screen, and therefore
perform an action while saving the new document. In this case, it
populates the user's email address from their dm_user profile into the title
attribute. However, this script could of course call all kinds of non-
properties functionality e.g. queue a rendition request, create an email
message object and so on.

var query = new DfQuery("select user_address from dm_user where


user_name = USER");
var coll = null;
try {
coll = query.execute(session, 0);
if (coll.next()) {
object.setString("title",
coll.getString("user_address"));
}
} finally {
if (coll!=null) {
coll.close();
}
}

Debugging from To debug from the Script Editor, just assign log into some variable and
the Script Editor put it at the end.

e.g.

var log = "test";


log += "\n test2";
...
throw log;

Continued on next page

7 Mar 2016 Page 371


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Script Examples, Continued

Category script If you have a one-to-on match of attribute names on the dm_folder
custom subtype and your dm_document custom subtype, you can use the
Property Initialization / Folder configuration to set that attribute to be
inherited from the folder onto new documents created in that folder.

Otherwise, the following script (e.g. as a Category configuration / Script


or Classification configuration / Script might be useful

var sourceAttr = "<attr_folder>";


var targetAttr = "<attr_document>";
var value = session.getObject(folderId).getString(sourceAttr);
model.set(targetAttr, value);
model.addModifiedProperty(targetAttr);

Custom Action – Scripts that are to process more than 1 selected object should use the
processing more “for” syntax e.g.
than one selected
object for (var i = 0; i < objects.size();i++) {
var obj = objects.get(i);
obj.promote(null,false,false);
obj.setTime("by_sent_date", new DfTime());
var sNextMajorVersion =
obj.getVersionPolicy().getNextMajorLabel();

obj.setRepeatingString("r_version_label",0,sNextMajorVersion);
obj.save();

Using ExtGWT You can use the OpenDialogWithURL to call out to an HTML page that
controls in a invokes a new servlet that extends the AbstractCaraServiceServlet. This
custom screen runs within the same application and allows you to get the session and
invoke Ext GWT controls.

However, you may require a separate ExtGWT development license for


this, please verify with www.sencha.com

Continued on next page

7 Mar 2016 Page 372


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Script Examples, Continued

New in v3.5.3 This version added new parameters to all scripts:


- sessionContext
- userName

It also added the following pararmeters to custom action scripts:


- operationFactory
- configFactory

So the CARA functionality can be called, e. g.

1. State change
var op =
operationFactory.getOperation(com.generiscorp.cara.dctm.api.operations.
ChangeStateOperation, sessionContext, repository);
op.setTargetState("Sent");
for (var i = 0; i < objects.size();i++) {
var obj = objects.get(i);
op.add(obj.getObjectId().getId());
}
op.execute();

2. Category validation
var categoryConfig = configFactory.getCategoryConfig(session);
if
(com.generiscorp.cara.dctm.api.utils.CaraDocumentCategoryValidator.is
ValidForObject(object,categoryConfig.findCategory(“Category Name”)))
{
//some category based processing
}

Password If you need to validate password at any point, you can use the Password
validation field type in a form (which masks the password) and then validate as
follows:

if (!context.validate(variables.get("username"),variables.get("password"),
session.getDocbaseName())) {
throw "Password not valid";
}

7 Mar 2016 Page 373


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Creating Help
Managing help To create and add Help items into CARA, simply create and store files in
files the following location, and they will be added automatically to the CARA
Help menu:

/ System / Applications / CARA3 / Help

To change the standard help files into a link to an external system, put the
URL in the "title" attribute into the help file. URL must start with http://

Help file for the A special case exists for the Portal. To have a help file open when users
Portal click the HELP button, you need the following files (one is for the
anonymous login help, one is for the logged in user help):

/System/Applications/CARA3/Help/Portal/CARA Portal Staff Help


/System/Applications/CARA3/Help/Portal/CARA Portal Public Help

7 Mar 2016 Page 374


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Changing the appearance


Replacing images To change the appearance of CARA, you can replace image files in the
following folders in the WAR file, keeping the same image dimensions:

.../ images
.../ images / file_types
.../ images / icons
.../ images / repos

Adding icons If you need new icons e.g. for folders, New Item Shortcuts, Dashboards
etc, add them to the following folder, and you can then select them in the
appropriate configurations. Such icons should be 16 x 16 resolution:

.../ images / icons

Of those, any icons that will be used for “adding” e.g. New Item
Shortcuts, should have “_add” at the end of their name e.g.

.../ images / generis_newdoc_add.png

Useful images to The images displayed on the CARA Desktop that you can replace are:
know about
.../ images / generis_logo.png
.../ images / generis_logo_small.png
.../ images / cara_logo_big.png
.../ images / cara_logo.png
.../ images / cara3.png

The image used at the top of the login screen is:

.../ images / repos / c3_dctm_small.png

The background on the main CARA Desktop is:

.../ gxt / desktop / images / desktop.gif

The browser tab icon is:

.../ favicon.ico

7 Mar 2016 Page 375


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Publishing Integration
What is... CARA allows integration with PDF publishing tools, both those from
Publishing Liquent (LES) and Generis (DocPublisher).
Integration
As part of the configuration, you need to create a Publishing
Configuration object:

1. Create a no content object of type cara_publishing_config


2. Save this object in /System/Applications/CARA3/Config
3. Apply the ACL “CARA Configuration” to the object
4. Modify the attributes:

publish_type Name of the publishing type, either CoreReports


or DocPublisher
publish_host Publishing host IP or DNS
publish_port Publishing host port
publish_templates Name of the templates available in the publishing
tool, will populate into the CARA Publish
Structure screen. Repeating
publish_user User as which to submit the job to the publishing
engine
publish_service_uri URI for the publishing web service
set_attribute Attribute name on the document to set (repeating)
set_value Value to set on the above attribute (repeating)

7 Mar 2016 Page 376


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Custom Content View


If you enable Customized View (custom view of content) you need to use custom hook - extend
CaraContentResolver class and override getContentOperation method which returns type of
operation (View, Preview, Edit, Download, OpenURL), e.g.

public class FdkContentResolver extends CaraContentResolver {

@Override
public CaraContentOperation getContentOperation(List<CaraContentRequest>
contentRequests, ICaraDctmSessionContext context,
String repository) throws CaraException {
logger.entry(contentRequests, context, repository);
IDfSession session = null;
try {
session = context.getSession(repository);

logger.debug("FDK: Content requests: {}", contentRequests !=


null ? contentRequests.size() : 0);

FdkWsImpl wsImpl = FdkUtil.getWSImpl(session);


if (contentRequests == null || contentRequests.size() > 1) {
logger.debug("FDK: Only one document can be selected");
throw new CaraValidationException("Please select just
one document");
}

CaraContentRequest cr = contentRequests.get(0);
String objectId = cr.getObjectId();
String format = cr.getFormat();
String pageModifier = cr.getPageModifier();

IDfSysObject object = (IDfSysObject)


session.getObject(DfUtil.toId(objectId));
if (object.isCheckedOutBy(null)) {
logger.debug("Returning Edit operation");
return new
CaraContentOperation(ContentOperationType.Edit, null);
}

logger.debug("FDK: Getting content operation for object: {}",


objectId);
if (FdkUtils.isFdkObject(object, session)) {
logger.debug("Object is an FDK object");
GetViewContentReturn result =
wsImpl.fdkViewContentInternal(objectId, format, pageModifier, false, null);
logger.debug("FDK ViewContentInternal result: {}",
result);
if (result != null) {
FdkViewContentData viewContentData =
result.getViewContentData();
logger.debug("ViewContentData: {}",
viewContentData);

7 Mar 2016 Page 377


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

String sCrxUrl = null;


if (null != viewContentData) {
Map<String, Object> paramsMap =
WsUtil.paramsToMap(viewContentData.getParams());
sCrxUrl = (String)
paramsMap.get(ViewContent.RETURN_PARAM_CRX_URL);
if (sCrxUrl != null && sCrxUrl.length() > 0)
{
logger.debug("Returning CRX URL: {}",
sCrxUrl);
return new
CaraContentOperation(ContentOperationType.OpenURL, sCrxUrl);
}

if (viewContentData.isAnnotateOnView()) {
logger.debug("Returning Preview
operation");
return new
CaraContentOperation(ContentOperationType.Preview, sCrxUrl);
}
}
}
} else {
logger.debug("Object is not an FDK object");
}
} catch (Throwable e) {
throw CaraExceptionHandlerUtil.handle(e);
} finally {
context.releaseSession(session);
}
CaraContentOperation result =
super.getContentOperation(contentRequests, context, repository);
logger.debug("Returning standard operation: {}", result.getType());
logger.exit(result.getType());
return result;
}

7 Mar 2016 Page 378


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Appendices
Procedure content
Copy and paste the content below into your procedure CARA3_Config_PostInstall that you attach
into your Configuration DocApp / DAR.

' ===================================================================================
' Written by: Mariusz Pala
' Copyright 2002-2010 Generis Knowledge Management Inc
' Purpose: Post-installation script for CARA3 Configuration
' ===================================================================================

Option Explicit

' Session variable


Private sSessionID as String

' Declarations
Declare Sub PostInstall (sDocbaseName as String, sUserName as String, sLoginTicket as String)

' ===================================================================================
' Originated By: Mariusz Pala
' Purpose: Script automatically executed at end of DocApp Install
' ===================================================================================
Sub PostInstall (sDocbaseName as String, sUserName as String, sLoginTicket as String)

Dim sInstallOwner as String


Dim sDocbaseOwner as String
Dim sDQL as String
Dim sCollection as String
Dim sObjectID as String
Dim iRet as Integer
Dim sFormatID as String
Dim sCabinetID as String
Dim sFolderID as String
Dim sEntryID as String
Dim sRootID as String
Dim sContextID as String
Dim sGroupID as String
Dim sLogID as String
Dim sCoreTemplateID as String

On Error Resume Next

' Open log file for this post install script


Open "C:\CARA3_Config_PostInstall_log.txt" for Output as #1

' Get docbase connection


sSessionID = dmAPIGet("connect," & sDocbaseName & "," & sUserName & "," & sLoginTicket)
Print #1, "Connected to Docbase: " & sDocbaseName & " as User: " & sUserName & " SessionID: " & sSessionID & "."

' Get the installation owner


sInstallOwner = dmAPIGet("get," & sSessionID & ",serverconfig,r_install_owner")
Print #1, "Documentum Installation Owner: " & sInstallOwner & "."

7 Mar 2016 Page 379


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

' Get the docbase owner


sDocbaseOwner = dmAPIGet("get," & sSessionID & ",docbaseconfig,owner_name")
Print #1, "Docbase Owner: " & sDocbaseOwner & "."

' Set the ACL and private cabinet for the Templates cabinet
sObjectID = dmAPIGet("id," & sSessionID & ",dm_cabinet where object_name = 'Templates'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Public Object")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",a_is_hidden","T")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Updated Security on Templates Cabinet."
Else
Print #1, "ERROR: Updating Security on Templates Cabinet."
End if

' Set BlankCoreTemplate ACL


sCoreTemplateID = ""
sCoreTemplateID = dmAPIGet("id,c,dm_document where folder('/Templates') and object_name = 'BlankCoreTemplate'")
If sCoreTemplateID <> "" then
iRet = dmAPIExec("fetch,c," & sCoreTemplateID)
iRet = dmAPISet("set,c," & sCoreTemplateID & ",acl_name","CARA Templates")
iRet = dmAPISet("set,c," & sCoreTemplateID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save,c," & sCoreTemplateID)
End if
If sCoreTemplateID <> "" and iRet = 1 then
Print #1, "Set ACL on BlankCoreTemplate in Templates cabinet."
elseif sCoreTemplateID <> "" and iRet = 0 then
Print #1, "ERROR: Unable to set ACL on BlankCoreTemplate in Templates cabinet"
end if

' Update security on CARA Config Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3') and object_name =
'Config'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Configuration ACL on Config folder in /System/Applications/CARA3."
Else
Print #1, "ERROR: Setting CARA Configuration ACL on Config folder in /System/Applications/CARA3."
End if

'Update security on methods


sDQL = "select r_object_id from dm_method where object_name like 'Cara%' or object_name like 'CARA%'"
sCollection = dmAPIGet("query," & sSessionID & "," & sDQL)
While dmAPIExec("next," & sSessionID & "," & sCollection) > 0
sObjectID = dmAPIGet("get," & sSessionID & "," & sCollection & ",r_object_id")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Method")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Method ACL on: " & dmAPIGet("get," & sSessionID & "," & sObjectID &
",object_name") & "."

7 Mar 2016 Page 380


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Else
Print #1, "ERROR: Setting CARA Method ACL on: " & dmAPIGet("get," & sSessionID & "," & sObjectID &
",object_name") & "."
End if
Wend
iRet = dmAPIExec("close," & sSessionID & "," & sCollection)

sDQL = "select r_object_id from dm_method where object_name='CaraCancelCheckout'"


sCollection = dmAPIGet("query," & sSessionID & "," & sDQL)
While dmAPIExec("next," & sSessionID & "," & sCollection) > 0
sObjectID = dmAPIGet("get," & sSessionID & "," & sCollection & ",r_object_id")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Cancel Checkout Method")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Cancel Checkout Method ACL on: " & dmAPIGet("get," & sSessionID & "," &
sObjectID & ",object_name") & "."
Else
Print #1, "ERROR: Setting CARA Cancel Checkout Method ACL on: " & dmAPIGet("get," & sSessionID &
"," & sObjectID & ",object_name") & "."
End if
Wend
iRet = dmAPIExec("close," & sSessionID & "," & sCollection)

' Update security on CARA Config Mailer Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3/Config') and
object_name = 'Mailer'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Configuration ACL on Mailer folder in /System/Applications/CARA3/Config."
Else
Print #1, "ERROR: Setting CARA Configuration ACL on Mailer folder in /System/Applications/CARA3/Config."
End if

' Update security on CARA Config Views Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3/Config') and
object_name = 'Views'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Views Folder")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Views Folder ACL on Views folder in /System/Applications/CARA3/Config."
Else
Print #1, "ERROR: Setting CARA Views Folder ACL on Views folder in /System/Applications/CARA3/Config."
End if

' Update security on Views objects


sDQL = "select r_object_id from cara_view"
sCollection = dmAPIGet("query," & sSessionID & "," & sDQL)
While dmAPIExec("next," & sSessionID & "," & sCollection) > 0
sObjectID = dmAPIGet("get," & sSessionID & "," & sCollection & ",r_object_id")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)

7 Mar 2016 Page 381


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Configuration CL on: " & dmAPIGet("get," & sSessionID & "," & sObjectID &
",object_name") & "."
Else
Print #1, "ERROR: Setting CARA Configuration ACL on: " & dmAPIGet("get," & sSessionID & "," &
sObjectID & ",object_name") & "."
End if
Wend
iRet = dmAPIExec("close," & sSessionID & "," & sCollection)

' Update security on CARA Config Capabilities Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3/Config') and
object_name = 'Capabilities'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Configuration ACL on Capabilities folder in /System/Applications/CARA3/Config."
Else
Print #1, "ERROR: Setting CARA Configuration ACL on Capabilities folder in /System/Applications/CARA3/Config."
End if

' Update security on Capabilities objects


sDQL = "select r_object_id from cara_capability"
sCollection = dmAPIGet("query," & sSessionID & "," & sDQL)
While dmAPIExec("next," & sSessionID & "," & sCollection) > 0
sObjectID = dmAPIGet("get," & sSessionID & "," & sCollection & ",r_object_id")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Configuration CL on: " & dmAPIGet("get," & sSessionID & "," & sObjectID &
",object_name") & "."
Else
Print #1, "ERROR: Setting CARA Configuration ACL on: " & dmAPIGet("get," & sSessionID & "," &
sObjectID & ",object_name") & "."
End if
Wend
iRet = dmAPIExec("close," & sSessionID & "," & sCollection)

' Update security on CARA Publishing Locks Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3/Config') and
object_name = 'Publishing Locks'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Publishing Lock")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Publishing Lock ACL on Publishing Locks folder in /System/Applications/CARA3/Config."
Else
Print #1, "ERROR: Setting CARA Publishing Lock ACL on Publishing Locks folder in
/System/Applications/CARA3/Config."

7 Mar 2016 Page 382


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

End if

' Update security on Workflows Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3') and object_name =
'Workflows'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Task Object ACL on Tasks folder in /System/Applications/CARA3."
Else
Print #1, "ERROR: Setting CARA Task Object ACL on Publishing Locks folder in /System/Applications/CARA3."
End if

' Update security on Workflow Templates Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3/Workflows') and
object_name = 'Templates'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Task Object")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Task Object ACL on Tasks folder in /System/Applications/CARA3."
Else
Print #1, "ERROR: Setting CARA Task Object ACL on Publishing Locks folder in /System/Applications/CARA3."
End if

' Update security on Workflow Types Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3/Workflows') and
object_name = 'Activity Types'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Task Object ACL on Tasks folder in /System/Applications/CARA3."
Else
Print #1, "ERROR: Setting CARA Task Object ACL on Publishing Locks folder in /System/Applications/CARA3."
End if

' Update security on Periodic Workflows Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3/Workflows') and
object_name = 'Periodic Workflows'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Task Object ACL on Tasks folder in /System/Applications/CARA3."
Else
Print #1, "ERROR: Setting CARA Task Object ACL on Publishing Locks folder in /System/Applications/CARA3."
End if

' Update security on Notifications Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3/Workflows') and
object_name = 'Notifications'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)

7 Mar 2016 Page 383


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Task Object ACL on Tasks folder in /System/Applications/CARA3."
Else
Print #1, "ERROR: Setting CARA Task Object ACL on Publishing Locks folder in /System/Applications/CARA3."
End if

' Update security on Not Template objects


sDQL = "select r_object_id from dm_sysobject where folder('/System/Applications/CARA3/Workflows', descend) "
sCollection = dmAPIGet("query," & sSessionID & "," & sDQL)
While dmAPIExec("next," & sSessionID & "," & sCollection) > 0
sObjectID = dmAPIGet("get," & sSessionID & "," & sCollection & ",r_object_id")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Configuration CL on: " & dmAPIGet("get," & sSessionID & "," & sObjectID &
",object_name") & "."
Else
Print #1, "ERROR: Setting CARA Configuration ACL on: " & dmAPIGet("get," & sSessionID & "," &
sObjectID & ",object_name") & "."
End if
Wend
iRet = dmAPIExec("close," & sSessionID & "," & sCollection)

' Update security on Searches Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3/Config') and
object_name = 'Searches'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Searches Folder")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Task Object ACL on Tasks folder in /System/Applications/CARA3."
Else
Print #1, "ERROR: Setting CARA Task Object ACL on Publishing Locks folder in /System/Applications/CARA3."
End if

' Update security on CARA objects


sDQL = "select r_object_id from dm_sysobject where folder('/System/Applications/CARA3',descend)"
sCollection = dmAPIGet("query," & sSessionID & "," & sDQL)
While dmAPIExec("next," & sSessionID & "," & sCollection) > 0
sObjectID = dmAPIGet("get," & sSessionID & "," & sCollection & ",r_object_id")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Configuration ACL on: " & dmAPIGet("get," & sSessionID & "," & sObjectID &
",object_name") & "."
Else
Print #1, "ERROR: Setting CARA Configuration ACL on: " & dmAPIGet("get," & sSessionID & "," &
sObjectID & ",object_name") & "."
End if
Wend

7 Mar 2016 Page 384


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

iRet = dmAPIExec("close," & sSessionID & "," & sCollection)

' Update security on Sequences Folder


sObjectID = dmAPIGet("id," & sSessionID & ",dm_folder where folder('/System/Applications/CARA3/Config') and
object_name = 'Sequences'")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Sequence")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Sequence ACL on Sequences folder in /System/Applications/CARA3/Config."
Else
Print #1, "ERROR: Setting CARA Sequence ACL on Sequences folder in /System/Applications/CARA3/Config."
End if

' Update security on Sequence objects


sDQL = "select r_object_id from CARA_sequence_config where
folder('/System/Applications/CARA3/Config/Sequences',descend)"
sCollection = dmAPIGet("query," & sSessionID & "," & sDQL)
While dmAPIExec("next," & sSessionID & "," & sCollection) > 0
sObjectID = dmAPIGet("get," & sSessionID & "," & sCollection & ",r_object_id")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Configuration")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Configuration ACL on: " & dmAPIGet("get," & sSessionID & "," & sObjectID &
",object_name") & "."
Else
Print #1, "ERROR: Setting CARA Configuration ACL on: " & dmAPIGet("get," & sSessionID & "," &
sObjectID & ",object_name") & "."
End if
Wend
iRet = dmAPIExec("close," & sSessionID & "," & sCollection)

' Update security on running sequence objects


sDQL = "select r_object_id from CARA_running_sequence where
folder('/System/Applications/CARA3/Config/Sequences',descend)"
sCollection = dmAPIGet("query," & sSessionID & "," & sDQL)
While dmAPIExec("next," & sSessionID & "," & sCollection) > 0
sObjectID = dmAPIGet("get," & sSessionID & "," & sCollection & ",r_object_id")
iRet = dmAPIExec("fetch," & sSessionID & "," & sObjectID)
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_name","CARA Sequence")
iRet = dmAPISet("set," & sSessionID & "," & sObjectID & ",acl_domain","dm_dbo")
iRet = dmAPIExec("save," & sSessionID & "," & sObjectID)
If iRet = 1 then
Print #1, "Set CARA Configuration ACL on: " & dmAPIGet("get," & sSessionID & "," & sObjectID &
",object_name") & "."
Else
Print #1, "ERROR: Setting CARA Configuration ACL on: " & dmAPIGet("get," & sSessionID & "," &
sObjectID & ",object_name") & "."
End if
Wend
iRet = dmAPIExec("close," & sSessionID & "," & sCollection)

' Import log file into docbase

7 Mar 2016 Page 385


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

sLogID = dmapiget("create," & sSessionID & ",dm_document")


iRet = dmapiset("set," & sSessionID & "," & sLogID & ",object_name", "CARA3_Config_PostInstall_log")
iRet = dmapiexec("link," & sSessionID & "," & sLogID & ",'/Temp'")
iRet = dmapiexec("setfile," & sSessionID & "," & sLogID & ",'C:\CARA3_Config_PostInstall_log.txt',crtext")
iRet = dmapiset("set," & sSessionID & "," & sLogID & ",acl_name","CARA Configuration")
iRet = dmapiset("set," & sSessionID & "," & sLogID & ",acl_domain","dm_dbo")
iRet = dmapiexec("save," & sSessionID & "," & sLogID)

' Disconnect from the docbase


iRet = dmAPIExec("disconnect," & sSessionID)

End Sub

7 Mar 2016 Page 386


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

CARA Jobs

Name Description Method Inactive

CARA ACL Housekeeper Deletes disused CARA ACLs CaraACLHousekeeper Yes

CARA Auto Promote Job to automatically promote documents based on CaraAutoPromote Yes
certain criteria

CARA Calculate Auto Recalculates auto values for the selected CaraCalculateAutoValues Yes
Values documents

CARA Mailer Sends the CARA Mail messages CaraMailer No

CARA Mailer Queue Cleaner Cleans the mail queue CaraMailerQueueCleaner No

CARA Not Started Cleans the workflows not started by the due date CaraNotStartedWorkflowsCleane No
Workflows Cleaner r

CARA Orphaned Workflows Cleans the orphaned workflows CaraOrphanedWorkflowsCleaner No


Cleaner

CARA Purge Job to automatically purge document based on CaraPurge No


configuration

CARA Staging Area Imports attachments from POP3/IMAP account CaraStagingAreaImporter No


Importer into Staging Area

CARA Start Periodic Starts periodic workflows CaraStartPeriodicWorkflows No


Workflows

7 Mar 2016 Page 387


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Name Description Method Inactive

CARA Structure Deletes orphan structure nodes and context objects CaraStructureHousekeeper3 Yes
Housekeeper

CARA Workflow Maintains workflow overdue notifications CaraWfNotificationsMaintainer Yes


Notifications Maintainer

CaraCleanTrashDocuments Removes documents in trash based on a cutoff date CaraCleanTrashDocuments Yes

CARAExecuteScript CARA Execute Script – Job to run other jobs that CaraExecuteScript Yes
are set up as CARA Script jobs rather than method
jobs

CaraSecurityLinkUpdate Updates the ACL on select documents CaraSecurityLinkUpdate Yes

7 Mar 2016 Page 388


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

CARA Methods
Name Type Method Verb Description
CaraACLHousekeeper java com.generiscorp.cara.dctm.jms.CaraACLHousekeeper CARA method to clean the CARA ACLs
com.generiscorp.cara.dctm.jms.CaraActivityChangeStateMet CARA method to change state of a
CaraActivityChangeState java
hod document after an activity completion
com.generiscorp.cara.dctm.jms.CaraActivityPostCompletionM CARA method executed after an activity
CaraActivityPostCompletion java
ethod completion
CARA method to assign documents in
CaraAssignDocument3 java com.generiscorp.cara.dctm.jms.CaraAssignDocumentMethod
structures
com.generiscorp.cara.dctm.jms.CaraAutoFinishActivitiesMeth CARA method to reject the tasks for all
CaraAutoFinishActivities java
od given criteria.
CARA method to automatically promote
CaraAutoPromote java com.generiscorp.cara.dctm.jms.CaraAutoPromoteMethod
documents
com.generiscorp.cara.dctm.jms.CaraCalculateAutoValuesMet CARA method to execute auto-values
CaraCalculateAutoValues java
hod processing on existing documents.
CARA method to remove lock from an
CaraCancelCheckout java com.generiscorp.cara.dctm.jms.CaraCancelCheckoutMethod
object
com.generiscorp.cara.dctm.jms.CaraChangeStructurePermiss CARA method to change structure
CaraChangeStructurePermissions3 java
ionsMethod permissions
com.generiscorp.cara.dctm.jms.CaraCleanTrashDocumentsM
CaraCleanTrashDocuments java CARA method to clean the Trash Can
ethod
com.generiscorp.cara.dctm.jms.CaraCustomActionExecutorM CARA method to execute a Custom Action
CaraCustomActionExecutor java
ethod as superuser.
com.generiscorp.cara.dctm.jms.CaraDocumentPostProcessin CARA method to run post-processing on a
CaraDocumentPostProcessing java
gMethod saved/checked-in document
CaraExecuteScript java com.generiscorp.cara.dctm.jms.CaraExecuteScriptMethod CARA
CARA method to grant a permission to a
CaraGrantPermissions java com.generiscorp.cara.dctm.jms.CaraGrantPermissionMethod
user
com.generiscorp.cara.dctm.jms.CaraInitializeStructurePermis CARA method to reset structure
CaraInitializeStructurePermissions3 java
sionsMethod permissions on creation
com.generiscorp.cara.dctm.jms.CaraInsertStructurePermissio CARA method to insert documents in a
CaraInsertStructurePermissions3 java
nsMethod structure
CaraMailer java com.generiscorp.cara.dctm.jms.CaraMailerMethod CARA method to send email notifications
com.generiscorp.cara.dctm.jms.CaraMailerQueueCleanerMet
CaraMailerQueueCleaner java CARA method to clean mailer queue
hod
CARA method to set the version number to
CaraMarkVersion java com.generiscorp.cara.dctm.jms.CaraMarkVersionMethod
0.0 or 0.1 or 1.0
com.generiscorp.cara.dctm.jms.CaraNotStartedWorkflowsCle CARA method to remove not started
CaraNotStartedWorkflowsCleaner java
anerMethod workflows
com.generiscorp.cara.dctm.jms.CaraOrphanedWorkflowsClea CARA method to clean orphaned
CaraOrphanedWorkflowsCleaner java
nerMethod workflows

7 Mar 2016 Page 389


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Name Type Method Verb Description


com.generiscorp.cara.dctm.jms.CaraPostStateChangeMetho CARA method to be executed on a state
CaraPostStateChange java
d change
CARA method to purge objects based on
CaraPurge java com.generiscorp.cara.dctm.jms.CaraPurgeMethod
configuration
CARA method to execute a DQL - works
CaraQueryExecutor java com.generiscorp.cara.dctm.jms.CaraQueryExecutorMethod
only run from a job.
com.generiscorp.cara.dctm.jms.CaraRejectInactiveUsersActiv CARA method to reject the tasks for all
CaraRejectInactiveUsersActivities java
itiesMethod inactive users
CaraRemoveInactiveUsersFromGrou com.generiscorp.cara.dctm.jms.CaraRemoveInactiveUsersFr CARA method to remove all inactive users
java
ps omGroupsMethod from all groups
CARA method to restore from the Trash
CaraRestoreTrash java com.generiscorp.cara.dctm.jms.CaraRestoreTrashMethod
Can
CARA method to calculate security and
CaraSecurityLink java com.generiscorp.cara.dctm.jms.CaraSecurityLinkMethod
folder location
com.generiscorp.cara.dctm.jms.CaraSecurityLinkUpdateMeth CARA method to recalculate security and
CaraSecurityLinkUpdate java
od folder location
CARA method to generates an object with
CaraSessionSpy java com.generiscorp.cara.dctm.jms.CaraSessionSpyMethod
session count info.
com.generiscorp.cara.dctm.jms.CaraStagingAreaImporterMet
CaraStagingAreaImporter java CARA
hod
CaraStartPeriodicWorkflows java com.generiscorp.cara.dctm.jms.CaraStartPeriodicWorkflows CARA method to start periodic workflows
CaraStateChange java com.generiscorp.cara.dctm.jms.CaraStateChangeMethod CARA method to be change lifecycle state
com.generiscorp.cara.dctm.jms.CaraStructureHousekeeperM CARA method to clean up orphaned
CaraStructureHousekeeper3 java
ethod structures
CARA method to test whether the JMS is
CaraTestMethod java com.generiscorp.cara.dctm.jms.CaraTestMethod
running
CaraTrash java com.generiscorp.cara.dctm.jms.CaraTrashMethod CARA method to Trash documents
CARA method to update dates for all given
CaraUpdateDates java com.generiscorp.cara.dctm.jms.CaraUpdateDatesMethod
documents
CaraUserRename java com.generiscorp.cara.dctm.jms.CaraUserRenameMethod CARA method to rename a user
com.generiscorp.cara.dctm.jms.CaraMaintainWorkflowOverdu CARA method to maintain the workflow
CaraWfNotificationsMaintainer java
eNotifications notifications

7 Mar 2016 Page 390


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Date formats
The following is an extract of the information from the GXT Project on date formatting.

DateTimeFormat

Formats and parses dates and times using locale-sensitive patterns.

Patterns

Symbol Meaning Presentation Example


G era designator Text AD
y year Number 1996
L standalone month in year Text or Number July (or) 07
M month in year Text or Number July (or) 07
d day in month Number 10
h hour in am/pm (1-12) Number 12
H hour in day (0-23) Number 0
m minute in hour Number 30
s second in minute Number 55
S fractional second Number 978
E day of week Text Tuesday
c standalone day of week Text Tuesday
a am/pm marker Text PM
k hour in day (1-24) Number 24
K hour in am/pm (0-11) Number 0
z time zone Text Pacific Standard Time(see comment)
Z time zone (RFC 822) Text -0800(See comment)
v time zone id Text America/Los_Angeles(See comment)
' escape for text Delimiter 'Date='
'' single quote Literal 'o''clock'

The number of pattern letters influences the format, as follows:

Text

if 4 or more, then use the full form; if less than 4, use short or abbreviated form if it exists (e.g.,
"EEEE" produces "Monday", "EEE" produces "Mon")

Number

the minimum number of digits. Shorter numbers are zero-padded to this amount (e.g. if "m"
produces "6", "mm" produces "06"). Year is handled specially; that is, if the count of 'y' is 2, the

7 Mar 2016 Page 391


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Year will be truncated to 2 digits. (e.g., if "yyyy" produces "1997", "yy" produces "97".) Unlike
other fields, fractional seconds are padded on the right with zero.

Text or Number

3 or more, use text, otherwise use number. (e.g. "M" produces "1", "MM" produces "01", "MMM"
produces "Jan", and "MMMM" produces "January". Some pattern letters also treat a count of 5
specially, meaning a single-letter abbreviation: L, M, E, and c.

Any characters in the pattern that are not in the ranges of ['a '..'z'] and ['A'..'Z'] will be treated as
quoted text. For instance, characters like ':', ' .', ' ' (space), '#' and ' @' will appear in the resulting
time text even they are not embraced within single quotes.

[Time Zone Handling] Web browsers don't provide all the information we need for proper time zone
formating -- so GWT has a copy of the required data, for your convenience. For simpler cases, one
can also use a fallback implementation that only keeps track of the current timezone offset. These
two approaches are called, respectively, Common TimeZones and Simple TimeZones, although both
are implemented with the same TimeZone class. "TimeZone createTimeZone(String timezoneData)"
returns a Common TimeZone object, and "TimeZone createTimeZone(int
timeZoneOffsetInMinutes)" returns a Simple TimeZone object. The one provided by OS fall into to
Simple TimeZone category. For formatting purpose, following table shows the behavior of GWT
DateTimeFormat.

Pattern Common TimeZone Simple TimeZone


z, zz, zzz PDT UTC-7
zzzz Pacific Daylight Time UTC-7
Z, ZZ -0700 -0700
ZZZ -07:00 -07:00
ZZZZ GMT-07:00 GMT-07:00
v, vv, vvv, vvvv America/Los_Angeles Etc/GMT+7

Parsing Dates and Times

The pattern does not need to specify every field. If the year, month, or day is missing from the
pattern, the corresponding value will be taken from the current date. If the month is specified but the
day is not, the day will be constrained to the last day within the specified month. If the hour, minute,
or second is missing, the value defaults to zero.

As with formatting (described above), the count of pattern letters determines the parsing behavior.

Text

4 or more pattern letters--use full form, less than 4--use short or abbreviated form if one exists. In
parsing, we will always try long format, then short.

7 Mar 2016 Page 392


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Number

The minimum number of digits.

Text or Number

3 or more characters means use text, otherwise use number

Although the current pattern specification doesn't not specify behavior for all letters, it may in the
future. It is strongly discouraged to use unspecified letters as literal text without quoting them.

[Note on TimeZone] The time zone support for parsing is limited. Only standard GMT and RFC
format are supported. Time zone specification using time zone id (like America/Los_Angeles), time
zone names (like PST, Pacific Standard Time) are not supported. Normally, it is too much a burden
for a client application to load all the time zone symbols. And in almost all those cases, it is a better
choice to do such parsing on server side through certain RPC mechanism. This decision is based on
particular use cases we have studied; in principle, it could be changed in future versions.

Examples

Pattern Formatted Text


"yyyy.MM.dd G 'at' HH:mm:ss vvvv" 1996.07.10 AD at 15:08:56 America/Los_Angeles
"EEE, MMM d, ''yy" Wed, July 10, '96
"h:mm a" 12:08 PM
"hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time
"K:mm a, vvvv" 0:00 PM, America/Los_Angeles
"yyyyy.MMMMM.dd GGG hh:mm aaa" 01996.July.10 AD 12:08 PM

7 Mar 2016 Page 393


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Some useful widgets


Please visit www.generisforum.com for more widgets by the CARA community.

Description DQL
Object IDs - perhaps one for an Select r_object_id, i_chronicle_id from dm_sysobject where
Administrator view (based on r_object_id = '${r_object_id } '
dm_sysobject)
Display list of people who have select owner_name, DATETOSTRING(r_creation_date,'dd-
annotated the document MM-yyyy') as creation_date from dm_note where r_object_id
in (select child_id from dm_relation where relation_name =
'DM_ANNOTATE' and parent_id = '${r_object_id}')
To get a direct URL to VIEW a select 'http://<server>/<cara-app-
document (the user will be name>/Content/<DocbaseName>/view/${r_object_id}/${a_con
prompted to login if there is no tent_type}/none/${object_name}' as URL, b.r_object_id from
active session): dm_docbase_config a,dm_document b where b.r_object_id =
'${r_object_id}'
e.g.
select
'http://www.generiscloud.com/cara/Content/Generis/view/${r_o
bject_id}/${a_content_type}/none/${object_name}' as URL,
b.r_object_id from dm_docbase_config a,dm_document b
where b.r_object_id = '${r_object_id}'
To get a direct URL to EXPORT select 'http:// <server>/<cara-app-
a document (the user will be name>/Content/<docbase>/export/${r_object_id}/${a_content_
prompted to login if there is no type}/none/${object_name}' as URL, b.r_object_id from
active session): dm_docbase_config a,dm_document b where b.r_object_id =
'${r_object_id}'
e.g.
select
'http://www.generiscloud.com/cara/Content/Generis/export/${r
_object_id}/${a_content_type}/none/${object_name}' as URL,
b.r_object_id from dm_docbase_config a,dm_document b
where b.r_object_id = '${r_object_id}'
To get a QR Reader barcode for http://chart.apis.google.com/chart?chl=http%3A%2F%2Fwww.
an object generiscloud.com%2Fcara%2F%23docbase%2F${r_object_id}
&chs=250x250&cht=qr&chld=H%7C0

Replace the www.generiscloud.com with your URL. Replace


the “cara” with the name of your deployed CARA application.
Replace “docbase” with the name of your docbase.

7 Mar 2016 Page 394


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

Dumping objects and modifying properties

Properties dump You can create a dump of the properties of a document by right-clicking
and selecting Dump. This will display the complete properties in a pop-
up screen, from where you can Copy ID, or Copy to clipboard so you
can paste the entire properties in some other application.

You can also toggle the checkbox to show / hide the system attributes
(those beginning a_, r_, or i_) and enter some Filter text (attribute name
or value) to filter the list.

To modify any attribute value, right-click on the value in the Value


column, and select Modify. You will then be shown an API window
pre-populated with the API to change the attribute, simply enter the
new value:

7 Mar 2016 Page 395


CONFIDENTIAL CARA v3.9.0 for Documentum - Configuration Manual

7 Mar 2016 Page 396

Das könnte Ihnen auch gefallen