Vous êtes sur la page 1sur 15

White Paper

EMC Documentum D2 External Widgets


A guide for developers

Abstract
This white paper explains how to use external widgets to extend
the capabilities of D2. It also documents the APIs provided by
D2 to allow communication between external widgets and the
rest of the D2 UI.

March 2013
Copyright 2013 EMC Corporation. All Rights Reserved.

EMC believes the information in this publication is accurate as


of its publication date. The information is subject to change
without notice.

The information in this publication is provided as is. EMC


Corporation makes no representations or warranties of any kind
with respect to the information in this publication, and
specifically disclaims implied warranties of merchantability or
fitness for a particular purpose.

Use, copying, and distribution of any EMC software described in


this publication requires an applicable software license.

For the most up-to-date listing of EMC product names, see EMC
Corporation Trademarks on EMC.com.

Part Number h11538

EMC Documentum D2 External Widgets 2


Table of Contents
Executive summary.................................................................................................. 4
Audience ............................................................................................................................ 4
Portal Communication ............................................................................................. 4
Messages................................................................................................................ 5
Message Settings ............................................................................................................... 5
Message Broadcasting Rules .............................................................................................. 5
Message Built-in Parameters .............................................................................................. 6
Widgets .................................................................................................................. 6
Widget Types ...................................................................................................................... 6
Widget States ..................................................................................................................... 6
Communication Channels ........................................................................................ 7
Event Channels .................................................................................................................. 7
Action Channels ................................................................................................................. 9
Javascript API ........................................................................................................ 13
Open Ajax Hub LIbrary ...................................................................................................... 13
D2 Open Ajax Hub API ...................................................................................................... 13
D2OpenAjaxHub Object................................................................................................ 13
OpenAjaxMessage Object ............................................................................................ 14
Conclusion ............................................................................................................ 15

EMC Documentum D2 External Widgets 3


Executive summary
External widgets provide a mechanism for customers and partners to extend the
EMC Documentum D2 UI by adding web content that are served by a separate
application, and loaded into an iframe in the D2 web page. In the 4.0 release, D2
offered only very limited connectivity between external widgets and the rest of the
application. Customers could only choose specific events that would cause the
external widget to be refreshed, and some parameterization capability for the widget
URL.
The D2 4.1 release adds the ability for external widgets to subscribe to and publish
events using a JavaScript API, greatly improving the possibility to create fully
integrated product features. This new JavaScript API is the main focus of this white
paper.

Audience
This white paper is intended for developers wishing to create extensions to the D2
interface. Basic familiarity with the D2 product and JavaScript development practices
is assumed.

Portal Communication
D2 is composed of several components:
- D2 portal and its widgets communicate which each other by sending and receiving
messages on dedicated communication channels.
D2 portal is composed of internal widgets and displays various workspaces.
- Each workspace has a unique container ID (uid) used to identify it and can contain
several widgets. Each widget contained in a workspace is aware of this uid. When a
widget communicates, only widgets inside the same workspace are aware of this. This is
the default behavior and it can be overridden. The portal itself is a container with
portal as uid.
- Widgets register themselves on a communication channel to be able to receive
messages published on this channel by other widgets (or even by itself). Widgets can
publish any message on any communication channel. A widget has a type and an id.
When a widget publishes a message, the ID of this widget is sent with the message.
- Communication channels are dedicated to specific tasks like Opening a document.
Messages contain various data such as the ID of a document.
- Messages are sent through the channels. They contain a map of string information that
can be easily analyzed / set using the provided API.

EMC Documentum D2 External Widgets 4


Messages
When sending a message you can set options to specify how and which widget will be able to
receive it.
Messages contain key/values pairs of data. These pairs of data are called parameters.
There are key/values data sent by default with every message but you can add any data you
want inside the message.

Message Settings
Here is the list of message settings that define which widgets, registered on the communication
channel, receive a message.
- Container UID: By default, you can only receive messages from widget sharing the same
container UID (i.e.: in the same workspace) automatically set to widgets current
container uid.
- Global: true or false When a message is defined as global, itll be sent to every
container default is false.
- Sender: The ID of the widget that send the message - automatically set.
- Target widget type: The type of widget to target with this message. The value is the same
as the Widget Type field in D2-Config (ex: BrowserWidget) default is null.
- Target widget ID: The ID of the widget to target. The value is the name of the widget
configuration in D2-Config. default is null.
- Excluded widget type: The type of widget to exclude. The value is the same as the
Widget Type field in D2-Config (ex: BrowserWidget) default is null.
- Excluded widget ID: The ID of the widget to exclude. The value is the name of the widget
configuration in D2-Config. default is null.
- Volatile: true or false. A volatile message is not saved by widgets to be replayed
when widget is set active- default is false.

Message Broadcasting Rules


Here is the order of the tests to check if a widget will receive a message:
1. The widget is registered on the same communication channel as the one used to publish
the message.
2. The message is sent by a widget in the same workspace or the message is global.
3. If an excluded type is specified, the widgets type is not of the same as the excluded
type.
4. If an excluded ID is specified, the widgets ID is not the same as the excluded id.
5. If a target type is specified, the widgets type is the same as the target type.
6. If a target ID is specified, the widgets ID is the same as the target id.
7. The target widget is active.

EMC Documentum D2 External Widgets 5


Once all these conditions are met, the widget receives the message. Its up to the developer to
decide if further filtering is necessary. For example, usually one would test if the widget that
sent the message is not the same as the one receiving it.

Message Built-in Parameters


Message contains built-in parameters for the most common values. When sending a message
you can add your own parameter too, of course.

Key Details
oam_id The object id, convenient field
oam_cuid The container uid of the sending widget
oam_global Set the message as global or not
oam_sender id of the sending widget
oam_value A value, convenient field
oam_target_type type of the target widget
oam_target_id id of the target widget
oam_excluded_type type of the excluded widget
oam_excluded_id id of the excluded widget
oam_volatile set the message volatile or not

Widgets
Widget Types
There are 4 types of widget in D2:
- Portal Widgets: These are internal widgets, instantiated by the portal only. They are not
listed in D2-Config as available widget types.
- D2 Internal Widgets: These are the widgets available in D2-Config minus the external
widgets.
- External widgets without bidirectional communication: Basically, these are iframes for
which the URL is refreshed (and resolved if containing $values) when it receives a
message.
- External widgets with bidirectional communication: These widgets are iframes too but
they communicate with the portal and other widgets in the same way as internal widgets
do, using messages and communication channel with the provided API.

Widget States
When a widget is not displayed, its state is set as inactive. This happens when the widget is
embedded in a tab container or an accordion container. The widget state changes to active
when the tab of the widget is displayed.
For performance reasons, the widgets that are not active dont handle the messages they
receive. This is the default behavior and it can be overridden in case of specific needs.
When an inactive widget receives a message, this message is stored by the widget for later use.
There is only one stored message, the latest one received. When the widget becomes active,

EMC Documentum D2 External Widgets 6


this stored message is replayed for the widget. This is the default behavior that can be
overridden by setting the message as volatile. A volatile message is never stored, thus never
replayed.

Communication Channels
The portal uses two types of channels to communicate:
- Event: these channels are used when an event happens. Its often used after an action
has been performed. For example, D2_EVENT_OBJECT_DESTROYED is the channel used
to publish message when an object has been destroyed. Messages sent through Events
channel contain information about the event that just happened. For example, it will
contain the ID of the destroyed document.
- Action: these channels are used to request to perform certain actions from the portal.
For example, the D2_ACTION_CONTENT_VIEW is used to request a document to be
downloaded and opened on the desktop. Messages sent through Actions channels
contain information about the action to be performed. For example, it will contain the ID
of the document to view.

The channel naming is just a convention used to easily understand what the purpose of each
channel is. With the API we provide you can use any channel name you want.

Event Channels
When receiving a message on an event channel, this message will contain information about
the event that just happened. Several widgets can send a message in the same channel and
sometimes the content of the message can be slightly different, with less or more parameters.
Almost every message has data filled in its built-in parameters. For example, the oam_id
parameter that specifies the ID of the object involved in the event. We will not specify those
parameters in the following list for readability.
Not every event channels are listed here. Some channels are only technical channels used by
the portal and should not be used for any other purpose.

CHANNEL NAME DETAILS


D2_EVENT_SELECT_OBJECT An object has been selected - it can be a folder or a document.
-parentId: ID of the parent object
D2_EVENT_SELECT_OBJECTS Multiple objects have been selected
-parentId: ID of the parent object
D2_EVENT_OBJECT_DESTROYED An object has been destroyed. It can be a folder, a document, a relation
etc.
D2_EVENT_OBJECT_CREATED An object has been created. It can be a folder, a document, etc.
D2_EVENT_FILTER_CHANGED The global filter of the workspace has been changed
D2_EVENT_PREFERENCES_CHANGED The preferences of the user has been changed
D2_EVENT_PREFERENCES_LOADED The preferences of the user has been loaded
D2_EVENT_CHECKOUT_STATE_CHANG A document checkout state has been changed
ED
D2_EVENT_WIDGET_GET_FOCUS A widget get the focus
D2_EVENT_SEARCH_SAVED A search has been saved
D2_EVENT_SEARCH_CATEGORY_CREAT A search category has been created

EMC Documentum D2 External Widgets 7


ED
D2_EVENT_WORKFLOW_ABORTED A workflow has been aborted
D2_EVENT_SELECT_TASK A task has been selected
D2_EVENT_SELECT_TASK_FOLDER A task folder has been selected
D2_EVENT_SELECT_TASK_NOTE A task note has been selected
D2_EVENT_SELECT_TASK_PERFORMER A task performer has been selected
D2_EVENT_TASK_READ_STATE_CHANG The read state of a task changed
ED
D2_EVENT_TASK_PRIORITY_CHANGED The priority of a task changed
D2_EVENT_TASK_PROCESSED A task has been forwarded or rejected
D2_EVENT_WIDGET_INITIALIZED A widget has been initialized
D2_EVENT_WORKSPACE_CLOSED A workspace has been closed
D2_EVENT_THEME_CHANGED The theme has been changed
- The theme data is sent within the message
D2_EVENT_RENDITION_ADDED A rendition has been added to a document
D2_EVENT_SELECT_TAXONOMY A taxonomy has been selected
D2_EVENT_SELECT_DICTIONARY A dictionary has been selected
D2_EVENT_SELECT_USER A user has been selected
D2_EVENT_SELECT_GROUP A group has been selected
D2_EVENT_SELECT_RELATION A relation has been selected
D2_EVENT_SELECT_AUDIT An audit has been selected
D2_EVENT_SELECT_DISTRIBUTION A distribution configuration has been selected
D2_EVENT_SELECT_WORKFLOWTRACK A workflow tracker has been selected
ER
D2_EVENT_SELECT_WORKFLOWACTIVIT A workflow activity has been selected
Y
D2_EVENT_SELECT_RENDITION A rendition has been selected
D2_EVENT_SELECT_RETENTION A retention has been selected
D2_EVENT_SELECT_MARKUP A markup has been selected
D2_EVENT_SELECT_SEARCH A search has been selected
D2_EVENT_SELECT_FACET A facet has been selected
D2_EVENT_SELECT_QUERYFORM A query form has been selected
D2_EVENT_VD_BINDING_VERSION_SET The version of a VD has been bounded
D2_EVENT_VD_TEMPLATE_SELECTED A VD template form has been selected

EMC Documentum D2 External Widgets 8


Action Channels
When sending a message on an action channel, the message will contain information about the
action to be performed. Several widgets can send a message to the same channel and
sometimes the content of the message can be slightly different, with less or more parameters.
Almost every message has data filled in its built-in parameters. For example, the oam_id
parameter that specifies the ID of the object involved in the action. We will not specify all of
those parameters in the following list for readability.
Not every action channel is listed here. Some channels are only technical channels used by the
portal and should not be used for any other purpose. Some other channels are not yet ready to
be used for an external call. In any case, if a channel is missing in this list, it is as intended.
CHANNEL NAME DETAILS
D2_ACTION_OPEN_FOLDER Request the opening of a folder in the portal.
Parameters : oam_id as the id of the folder to open
D2_ACTION_OPEN_VD Request the opening of a VD in the portal.
Parameters : oam_id as the id of the VD to open
D2_ACTION_SEARCH_DOCUMENT Request the search to execute and display in the portal
Parameters: oam_id as the id of the search or last_search
D2_ACTION_LOCATE_OBJECT Request locating of an object in the portal.
Parameters : oam_id as the id of the object to locate
D2_ACTION_LOCATE_TASK Request locating of a task in the portal.
Parameters : oam_id as the id of the task to locate
D2_ACTION_LOCATE_SEARCH Request locating of a search in the portal.
Parameters : oam_id as the id of the task to locate
D2_ACTION_REFRESH_DOCUMENT Refresh the widget where the document is displayed
Parameters : oam_id as the id of the document
D2_ACTION_REFRESH_WIDGET Refresh the widget with the target_type.
Note that for now not all widgets implements the refresh feature
D2_ACTION_RELOAD_WORKSPACE Reload the current workspace ( using the oam_cuid )
D2_ACTION_COPY_LINK_IN_CLIPBOARD Copy the link to the object in the clipboard
Parameters : oam_id as the id of the object to create link of
D2_ACTION_DUMP Display a dump of the object
Parameters : oam_id as the id of the object to dump
D2_ACTION_CONTENT_CHECKIN Request the checkin of a document
Parameters : oam_id as the id of the document to checkin
D2_ACTION_CONTENT_IMPORT_AS_VERSION Request import as version for a document
Parameters : oam_id as the id of the document
D2_ACTION_CONTENT_CHECKIN_NATIVE_ANN Request the checkin of the native annotation of a document
OTATION Parameters : oam_id as the id of the document
D2_ACTION_CONTENT_PRINT Request print of a document
Parameters : oam_id as the id of the document to print
D2_ACTION_CONTENT_COMPARE Request comparison of 2 documents
Parameters : oam_id as the ids of the document to compare
D2_ACTION_CONTENT_EXPORT Request export of a document
Parameters : oam_id as the id of the document to export
D2_ACTION_CONTENT_VIEW Request view of a document
Parameters : oam_id as the id of the document to view
D2_ACTION_CONTENT_VIEW_NATIVE Request native view of a document
Parameters : oam_id as the id of the document to view
D2_ACTION_CONTENT_EDIT Request edit of a document
Parameters : oam_id as the id of the document to edit
D2_ACTION_CONTENT_CHECKOUT Request checkout of a document
Parameters : oam_id as the id of the document to checkout
D2_ACTION_CONTENT_CANCEL_CHECKOUT Request cancel checkout of a document
Parameters : oam_id as the id of the document to cancel checkout for
D2_ACTION_CONTENT_EDIT_WITH_NATIVE_A Request edit of a document with native annotation
NNOTATION Parameters : oam_id as the id of the document to edit

EMC Documentum D2 External Widgets 9


D2_ACTION_CONTENT_VIEW_WITH_NATIVE_A Request view of a document with native annotation
NNOTATION Parameters : oam_id as the id of the document to view
D2_ACTION_CONTENT_EDIT_NATIVE_ANNOTA Request edit native annotation of a document
TION Parameters : oam_id as the id of the document to edit
D2_ACTION_COMMENT Request display of the comment dialog
Parameters :
- oam_id as the id of the document to comment
- parentCommentId as the parent comment
D2_ACTION_CONTENT_CREATE Request display of the creation dialog
Parameters :
- oam_id as the id of the base document that can be used for
inheritance
- parentId as the parent folder. This folder is used to create the
document inside it if no autolink is set
D2_ACTION_CONTENT_IMPORT Request display of the import dialog
Parameters :
- oam_id as the id of the base document that can be used for
inheritance
- parentId as the parent folder. This folder is used to create the
document inside it if no autolink is set
- files as a list of files on the client machine. This will populate the
list
D2_ACTION_FOLDER_CREATE Request display of the folder creation dialog
Parameters :
- root_object_type set to dm_folder or dm_cabinet
D2_ACTION_OBJECT_DESTROY Request display of the destroy dialog
Parameters :
- oam_id as the id of the object to destroy
- parentId as the id of the objects parent
D2_ACTION_DISTRIBUTION_ACCEPT Accept the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name
D2_ACTION_DISTRIBUTION_REJECT Reject the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name
D2_ACTION_DISTRIBUTION_PREPARE Prepare the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name
D2_ACTION_DISTRIBUTION_LAUNCH Launch the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name
D2_ACTION_DISTRIBUTION_STOP Stop the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name

EMC Documentum D2 External Widgets 10


D2_ACTION_DISTRIBUTION_REPORT Report the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name
D2_ACTION_LIFECYCLE_DCTM Request an operation on a Documentum lifecycle (D2 lifecycle operations
are not supported yet)
Parameters :
- oam_id as the id of the object
- operation as the operation to perform
- policyId as the id of the policy to use
D2_ACTION_PERMISSIONS_SHOW Request display of the permissions dialog
Parameters : oam_id as the id of the object
D2_ACTION_ADVANCED_SEARCH Request display of the advanced search dialog
D2_ACTION_PREFERENCES_SHOW Request display of the user preferences dialog
D2_ACTION_QUERYFORM_SHOW Request display of the query form dialog
Parameters : oam_id as the id of the query form
D2_ACTION_RENDITION_ADD Request display of the add rendition dialog
Parameters : oam_id as the id of the document to add rendition to
D2_ACTION_RENDITION_REQUEST Request rendition for a document
Parameters : oam_id as the id of the document
D2_ACTION_SYNCPLICITY Request display of the Syncplicity dialog for a document
Parameters : oam_id as the id of the document
D2_ACTION_VD_ADD_CHILD_SELECTED Request display of the add child dialog for the current selected item in the
VD widget
D2_ACTION_VD_REMOVE_CHILD_SELECTED Request display of the remove child dialog for the current selected item in
the VD widget
D2_ACTION_VD_SET_CHILD_BINDING_VERSI Request setting of binding version of the current selected item in the VD
ON widget
D2_ACTION_VD_INSERT_INHERITED_COMPON Request display of the inserted inherited component dialog for the current
ENT selected item in the VD widget
D2_ACTION_VD_CLEAR_VD Request the VD widget to clear its content
D2_ACTION_WORKFLOW_LAUNCH Launch a workflow for a document.
Parameters :
- oam_id as the id of the document
- config as the workflow configuration name to use
D2_ACTION_WORKFLOW_LAUNCH_SCHEDULE Launch a scheduled workflow for a document.
D Parameters :oam_id as the queue_item
D2_ACTION_WORKFLOW_UPDATE_PERFORME Request display of the update performers dialog
RS Parameters :oam_id as the queue_item
D2_ACTION_WORKFLOW_ABORT Request display of the abort workflow dialog
Parameters :oam_id as the tracker
D2_ACTION_TASK_ACQUIRE Set the task as acquired
Parameters :
- oam_id as the id of the task
- forceAcquire to force acquisition if true
- forceRead to force read if true
D2_ACTION_TASK_READ Set the task as read/unread
Parameters :
- oam_id as the id of the task
- read if true, unread otherwise
D2_ACTION_TASK_PRIORITY Set the task priority
Parameters :
- oam_id as the id of the task

EMC Documentum D2 External Widgets 11


- priority ( integer as string )
D2_ACTION_TASK_FORWARD Request display of the task forward dialog
Parameters : oam_id as the id of the task
D2_ACTION_TASK_REJECT Request display of the task reject dialog
Parameters : oam_id as the id of the task
D2_ACTION_TASK_DELEGATE Request display of the task delegate dialog
Parameters :
- oam_id as the id of the task
- source : tracker or task
D2_ACTION_TASK_NOTE Request display of the task note dialog
Parameters : oam_id as the id of the task
D2_ACTION_TASK_PROCESS Request display of the task process dialog
Parameters :
- oam_id as the id of the task
- operation to perform
D2_ACTION_TAXONOMY_EXPORT Request display of the export taxonomy dialog
Parameters : oam_id as the id of the taxonomy
D2_ACTION_TAXONOMY_IMPORT Request display of the import taxonomy dialog
Parameters : oam_id as the id of the taxonomy
D2_ACTION_TAXONOMY_CHECKIN Request display of the checkin taxonomy dialog
Parameters : oam_id as the id of the taxonomy
D2_ACTION_TAXONOMY_SAVE Request display of the save taxonomy dialog
Parameters : oam_id as the id of the taxonomy
D2_ACTION_TAXONOMY_PROPERTIES Request display of the taxonomy properties dialog
Parameters : oam_id as the id of the taxonomy
D2_ACTION_TAXONOMY_LOCATE Request locate of the taxonomy
Parameters : oam_id as the id of the taxonomy
D2_ACTION_TAXONOMY_RESTORE Request display of the restore taxonomy dialog
Parameters : oam_id as the id of the taxonomy
D2_ACTION_DICTIONARY_EXPORT Request display of the export dictionary dialog
Parameters : oam_id as the id of the dictionary
D2_ACTION_DICTIONARY_IMPORT Request display of the import dictionary dialog
Parameters : oam_id as the id of the dictionary
D2_ACTION_DICTIONARY_SAVE Request display of the save dictionary dialog
Parameters : oam_id as the id of the dictionary
D2_ACTION_DICTIONARY_RESTORE Request display of the restore dictionary dialog
Parameters : oam_id as the id of the dictionary
D2_ACTION_DICTIONARY_UPDATE Request display of the update dictionary dialog
Parameters : oam_id as the id of the dictionary
D2_ACTION_DICTIONARY_PROPERTIES Request display of the dictionary properties dialog
Parameters : oam_id as the id of the dictionary
D2_ACTION_RELATION_CREATE Request display of the relation creation dialog
Parameters : oam_id as the id of the document to create a relation with
D2_ACTION_RELATION_DESTROY Request display of the relation destroy dialog
Parameters :
- oam_id as the id of the document to destroy a relation with
- associate_id is the id of the relation to destroy
D2_ACTION_MASS_UPDATE Launch a mass update for a document.
Parameters :
- oam_id as the id of the document
- config_name as the mass update configuration name to use

EMC Documentum D2 External Widgets 12


JavaScript API
To be able to use the communication channels and messages in your external widget youll
need two (2) JavaScript libraries:
- The Open Ajax Hub library
- The D2 Open Ajax Hub API
You can find these 2 files inside the D2.war in /container

Open Ajax Hub Library


Communication channels and messages use the Open Ajax Hub API.
This is a JavaScript library provided by the Open Ajax Alliance. Specifications can be found
here: http://www.openajax.org/member/wiki/OpenAjax_Hub_2.0_Specification
The current version we use in D2 is the 2.0.7 based on the 2.0 Specifications.
We provide 2 files:
- /container/external-api/ OpenAjaxManagedHub-all.js which is a not obfuscated version
of the library, based on the sources, intended to be used only for development
purposes.
- /container/ OpenAjaxManagedHub-all-obf.js which is the obfuscated version used by
D2, intended to be used in production.

D2 Open Ajax Hub API


We built the D2 communication system upon the Open Ajax Hub technology.
The JavaScript library can be found in /container/external-api/D2-OAH.js

D2OpenAjaxHub Object
The D2OpenAjaxHub object is the main object youll have to use to connect to the Open Ajax
Hub, send and receive messages.

1. Connecting to the Open Ajax Hub


This is achieved by the function connectHub
D2OpenAjaxHub.connectHub = function(fOnConnectCompleted, fOnInit, fOnActive)

When calling the connectHub function, you have to specify 3 callback functions :
fOnConnectCompleted(oHubClient, bSuccess, bError). This function is called at the end
of the hub connection.
o oHubClient: the Open Ajax Hub Client object created
o bSuccess: true if the hub is connected
o bError: true if an error occured
fOnInit(oMessage): This function is called when the widget is connected with the portal
and received some initialization data.

EMC Documentum D2 External Widgets 13


o oMessage: an Open Ajax Message that contains a list of the available
communication channel and the current workspace theme data.
fOnActive(bActive): This function is called when the widget is set active/inactive.
o bActive: true if the widget is set to active, false if set to inactive.

2. Registering on a channel
To register a channel, you must use the function subscribeToChannel
D2OpenAjaxHub.subscribeToChannel = function(sChannel, fCallbackDataReceived,
bHandleMessageIfInactive)
When calling the subscribeToChannel function, you have to specify 3 parameters:
sChannel: The channel to which your widget will register
fOnConnectCompleted(sChannel, oMessage). This function is called when the widget
receives a message(according to message broadcasting rules).
o sChannel: the channel where the message has been received.
o oMessage: the received message.
bHandleMessageIfInactive: True to make messages handled even if the widget is
inactive.

3. Sending a message on a channel


To send a message on a channel, you must use the function sendMessage
D2OpenAjaxHub.sendMessage = function(sChannel, oMessage)
When calling the sendMessage function, you have to specify 2 parameters:
sChannel: The channel to which your widget will register
oMessage. The message to send

OpenAjaxMessage Object
The Open Ajax Message is used to transfer data on the hub. Basically its a map of key/values.
When its transferred on a channel, it is serialized to a String form.
The JavaScript object we provided helps to serialize/deserialize it, to get and put data inside and
to specify the message broadcasting rules.

OpenAjaxMessage.isGlobal(): returns true if the message is global


OpenAjaxMessage.setGlobal(bGlobal): set the message global or not
OpenAjaxMessage.getId(bRaw): returns the ID of the object (oam_id parameter) . The
oam_id can contain multiple ids. if bRaw is set to true, the raw ID parameter is returned,
otherwise only the first ID is returned.
OpenAjaxMessage.getIds(): returns an array of string of the ids in the oam_id parameter
OpenAjaxMessage.setId(sId): set the oam_id parameter

EMC Documentum D2 External Widgets 14


OpenAjaxMessage.setIds(aIds): set a list of ids in the oam_id parameter (aIds is an array of
string)
OpenAjaxMessage.isMultipleIds(): returns true if the oam_id contains multiple ids
OpenAjaxMessage.getTargetType(): returns the type of the targeted widget
OpenAjaxMessage.setTargetType(sTarget): set the type of the targeted widget
OpenAjaxMessage.getTargetId(): returns the ID of the targeted widget
OpenAjaxMessage.setTargetId(sTarget): set the ID of the targeted widget
OpenAjaxMessage.getExcludedType(): returns the type of the excluded widget
OpenAjaxMessage.setExcludedType(sExcluded): set the type of the excluded widget
OpenAjaxMessage.getExcludedId(): returns the ID of the excluded widget
OpenAjaxMessage.setExcludedId(sExcluded): set the ID of the excluded widget
OpenAjaxMessage.getContainerUid(): return the oam_cuid parameter
OpenAjaxMessage.setContainerUid(sContainerUid) set the oam_cuid parameter
OpenAjaxMessage.isVolatile(): returns true if the message is volatile
OpenAjaxMessage.setVolatile(bVolatileEvent): set the message volatile or not
OpenAjaxMessage.getSender(): returns the sender widget id
OpenAjaxMessage.setSender(sSender): set the sender widget id. This is set automatically
when sending a message.
OpenAjaxMessage.getValue(): returns the value of the oam_value parameter
OpenAjaxMessage.setValue(sValue): set the value of the oam_value parameter
OpenAjaxMessage.get(key): returns the value set for this key
OpenAjaxMessage.put(key, value): set a value for a key. If the key already exists, the value
is replaced
OpenAjaxMessage.remove(key): removes the value with the key
OpenAjaxMessage.removeAll(): removes all values
OpenAjaxMessage.contains(key): returns true if the key exists in the message

Conclusion
As we have seen, D2 4.1 includes an extensive interface for sending and receiving UI
events from an external widget. Using the information in this white paper, it should
be possible to create widgets that are well coupled with the rest of the user interface.

EMC Documentum D2 External Widgets 15