Beruflich Dokumente
Kultur Dokumente
0 for
Documentum
Configuration Manual
7 Mar 2016
Table of contents
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
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
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.
Mandatory Overview
configurations The following requirements are mandatory, and should be done in the
following order.
Groups
Add users to the relevant groups (cara_*).
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”).
Category Definition
Define any required Categories in the Categories Definition, at a
minimum one (e.g. “All Documents” where DQL is 1=1).
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.
Versioning Each time you modify a configuration in CARA, the configuration object
configuration is versioned automatically.
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.
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.
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.
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.
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:
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.
object.mark("LOCKED");
object.save();
This sets a version label of LOCKED. To reverse it, just remove this
version label.
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.
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”.
Adding a User From the CARA Start menu, select the Control Panel and click on
Capability General / User Capabilities.
2. Select the desired role from the list and click Add:
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.
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
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:
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:
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.
View Management
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):
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.
Columns
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.
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:
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.
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:
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:
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.
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.
To set Attribute Filters, navigate to the 2nd tab, and click to add a filter,
entering the attribute information:
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:
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:
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.
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.
You can also select the checkbox to Sort dimension sets alphabetically.
Finally, on the Settings tab, you can specify queries behind individual
Dimensions:
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
This also allows for using Display Aliases for attributes where they exist.
Results in:
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.
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).
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
Check the box to display the labels as well as the button, the result will
be:
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.
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:
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:
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:
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.
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).
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):
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:
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:
You may also use ${var} syntax in the property initialization, e.g.:
object_name=${i_cabinet_id}
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
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
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).
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
Search config The Search config configuration allows you to define searches for users.
The General tab allows you to set
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.
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
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.
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.
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.
Advanced Search
configuration
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:
To add an attribute as searchable, click Add, select the attribute you wish
to add, and click Add:
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.
Query: Enter the DQL statement which will provide the list of
drop-down values for the user to select from:
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
THIS [where] syntax is not supported in the Portal so for the Portal saved
search do not use this.
You can also reference any of the attributes used in the Classification,
without having to explicitly add them as search fields.
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)
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.
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.
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:
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.
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.
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):
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.
Please see the Appendices for some useful widgets you may want to
create.
SMALL THUMBNAIL
Add rendition where Format = JPEG Thumbnail
Page Modifier = small_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 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
Finally, you can set if the Import Landing Zone will automatically open
the New Document screen on drag and drop or not:
Settings
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).
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).
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.
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.
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.
`
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>
The user can then change the display label in the Cabinet Restrictions
screen in CARA (see the CARA User Guide for details).
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.
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:
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.
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.
Dashboard The General tab allows definition of the basics of the Report:
Reports – General
Tab
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.
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.
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.
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:
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
which case only those users / groups will see the dashboard.
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
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
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:
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.
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.
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.
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:
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.
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:
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.
Sequences Configuration
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:
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.
Staging Area
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:
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:
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.
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.
Using scripts from To use a script, simply have a function in the script library script that you
the library can call e.g.:
LifeCycle
Lifecycle Configuration
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:
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:
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).
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 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();
Configuring a state If you select to delete previous versions of a particular status, select the
(cont’d) status to delete.
On the Notifications tab you can set the users or groups to notify on a
document getting to the particular state.
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):
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).
Configuring On the Conditions tab, you can define additional conditions for when the
transitions (cont’d) transition is allowed:
Configuring
transitions (cont’d)
Configuring
transitions (cont’d)
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.
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.
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
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.
Modifying a Dictionary
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.
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.
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:
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:
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.
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
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
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
Taxonomy Manager
Opening a taxonomy
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.
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.
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)
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.
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:
Registered Tables
Modifying registered table data
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
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.
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.
Classification Configuration
Classification Definition
How to … set 1. From the CARA Start menu, select the Control Panel and click on
classification Classification / Definition
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).
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)
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
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.
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.
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.
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.
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:
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.
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
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:
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.
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:
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:
<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})>
<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>})>
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:
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.
Scripts Configuration
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:
3. To add a script, click the magnifying glass next to the script window.
A writing window appears:
MS Document Extraction
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:
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:
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
MS Document Population
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:
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.
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.
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
How to … view a 1. Open the Forms Configuration, choose any listed item representing an
Forms existing configuration and click Edit.
configuration
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.
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:
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.
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:
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 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)
OR between them)
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.
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:
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).
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.
Or
Select the parent control (e.g. Tab) and click Add, then select Grid.
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.
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 Reset Properties tab, choose whether the grid should reset after a
change in any of the available attributes listed.
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
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:
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.
Enter the values (one per line) that will create the selection list for users.
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.
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
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).
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.
TYPE: Script
This allows you to define a script which will provide the values for the
assistance, e.g.:
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.
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.
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.
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.
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).
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.
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.
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:
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 the Fixed Width (pixels) or leave it blank to use the application
defaults. Define the Margins as described on page 198.
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 the Fixed Width (pixels) or leave it blank to use the application
defaults. Define the Margins as described on page 198.
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.
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 the Fixed Width (pixels) or leave it blank to use the application
defaults.
items:
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 the Fixed Width (pixels) or leave it blank to use the application
defaults. Define the Margins as described on page 198.
Dual list field Dual list field - Provides secondary dialog with values list to pick
multiple values:
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 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.
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).
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.
See the notes in the following sections for using the List template and List
width (pixels, leaving this blank uses the application defaults).
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
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>
study_number=study_number
site=keywords
This would result in the single combo showing (and setting) multiple
fields:
repeating_field=split(single_field, "separator")
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:
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 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.
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. Set the Grid Height or leave it
empty to have the application default used.
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.
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
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
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.
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:
Properties DQL
Select, set Both DQL select and set statements can be used in the DQL for a
property control.
{owner_name}</span></h3>{r_version_label}<br
/></div></tpl>
Item selector:
div.search-item
$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.
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.
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:
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
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.
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
How to … edit an Open the Audit configuration as above. Select a category and an audit
audit definition
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.
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:
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:
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.
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:
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
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.
Linking Configuration
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:
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
For example
/Quality Documents/Originating Year <case_id,substr(0,-6)>/Project ending in
<project_number,substr(-1)>
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'
Versioning Configuration
NOTE: previously called Check In / Checkout Configuration
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:
How to … 1. From the CARA Start menu, select the Control Panel and click on
configure Check In
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.
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
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:
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;
IMPORTANT – You should at a minimum probably have two configuration, one with the
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.
Legal Hold
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.
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)
DCN Configuration
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.
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
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.
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:
Task Configuration
Task Types
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.
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)
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
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.
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}'
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
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:
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.
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.
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.
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:
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:
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:
How to… define 1. Open the Control Panel and click on Tasks / Periodic Task
periodic tasks Definitions
2. The Periodic Task dialog appears:
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.
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.
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.
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
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:
Notification Templates
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:
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:
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/#<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
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
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.
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.
Users, Continued
Users, Continued
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:
Groups
What is group CARA provides the functionality to create, modify and delete
management? Documentum groups, as an alternative to working with Documentum
Administrator.
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
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.
2. In the screen that appears, select “Group” and enter at least the
mandatory information (underlined) and other information as
required, as follows:
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:
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.
Domains, Continued
2. In the screen that appears, select “Domain” and enter at least the
mandatory information (underlined) and other information as
required, as follows:
Domains, Continued
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:
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.
Roles, Continued
2. In the screen that appears, select “Role” and enter at least the
mandatory information (underlined) and other information as
required, as follows
Roles, Continued
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:
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:
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.
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:
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:
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.
How to … manage
Object Types
(cont’d)
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.
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.
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:
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:
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.
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
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’
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
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
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)
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
- docbase_name
- user_name
- object_id
- activity_id
- target_state
com.generiscorp.cara.dctm.jms.CaraAssignDocumentMethod
- docbase_name
- user_name
- object_id
- parent_node_id
- node_id
- node_containment_id
- contributors
- consumers
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
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)
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:
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.
CARA_USER PREFERENCES
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.
Execute Script
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.
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.
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.
DQL Query:
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.
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
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
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:
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.
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.
object.setContentType(CaraFileFormatDetector.detectFor
mat(files.get(i).getFileName(), session));
object.setFile(files.get(i).getFilePath());
object.save();
}
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:
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
Enable advanced
conditions
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.
Completion Tab On the Completion tab, you define the list of options to execute at the end
of a custom action:
View - opens the object for Viewing for the ID variable specified
View PDF - opens the object for Viewing PDF for the ID variable
specified
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
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.
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==
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.
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
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!");
}
}
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:
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:
dfc.search.ecis.enable=true
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.
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.
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.
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.
How to save a DQL DQL searches are saved automatically in a “most recently used”
search dropdown of Saved queries.
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).
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
*/
/**
* 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);
}
Script Editor
Script Editor The Script Editor allows you to enter a script and test it for correctness:
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.
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).
Scripts – run as If you write a CARA Script, you can have it executed periodically as a
job job. To do this:
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");
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.
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
}
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.
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.
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.
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.
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.
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";
}
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:
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):
.../ 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:
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.
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
.../ favicon.ico
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:
@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);
CaraContentRequest cr = contentRequests.get(0);
String objectId = cr.getObjectId();
String format = cr.getFormat();
String pageModifier = cr.getPageModifier();
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;
}
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
' 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)
' 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
Else
Print #1, "ERROR: Setting CARA Method ACL on: " & dmAPIGet("get," & sSessionID & "," & sObjectID &
",object_name") & "."
End if
Wend
iRet = dmAPIExec("close," & sSessionID & "," & sCollection)
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)
End if
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
End Sub
CARA Jobs
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 Not Started Cleans the workflows not started by the due date CaraNotStartedWorkflowsCleane No
Workflows Cleaner r
CARA Structure Deletes orphan structure nodes and context objects CaraStructureHousekeeper3 Yes
Housekeeper
CARAExecuteScript CARA Execute Script – Job to run other jobs that CaraExecuteScript Yes
are set up as CARA Script jobs rather than method
jobs
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
Date formats
The following is an extract of the information from the GXT Project on date formatting.
DateTimeFormat
Patterns
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
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.
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.
Number
Text or 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
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
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.