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

EMC Documentum D2 External Widgets 7

ED
D2_EVENT_WORKFLOW_ABORTED
D2_EVENT_SELECT_TASK
D2_EVENT_SELECT_TASK_FOLDER
D2_EVENT_SELECT_TASK_NOTE
D2_EVENT_SELECT_TASK_PERFORMER
D2_EVENT_TASK_READ_STATE_CHANG
ED
D2_EVENT_TASK_PRIORITY_CHANGED
D2_EVENT_TASK_PROCESSED
D2_EVENT_WIDGET_INITIALIZED
D2_EVENT_WORKSPACE_CLOSED
D2_EVENT_THEME_CHANGED
D2_EVENT_RENDITION_ADDED
D2_EVENT_SELECT_TAXONOMY
D2_EVENT_SELECT_DICTIONARY
D2_EVENT_SELECT_USER
D2_EVENT_SELECT_GROUP
D2_EVENT_SELECT_RELATION
D2_EVENT_SELECT_AUDIT
D2_EVENT_SELECT_DISTRIBUTION
D2_EVENT_SELECT_WORKFLOWTRACK
ER
D2_EVENT_SELECT_WORKFLOWACTIVIT
Y
D2_EVENT_SELECT_RENDITION
D2_EVENT_SELECT_RETENTION
D2_EVENT_SELECT_MARKUP
D2_EVENT_SELECT_SEARCH
D2_EVENT_SELECT_FACET
D2_EVENT_SELECT_QUERYFORM
D2_EVENT_VD_BINDING_VERSION_SET
D2_EVENT_VD_TEMPLATE_SELECTED
A workflow has been aborted
A task has been selected
A task folder has been selected
A task note has been selected
A task performer has been selected
The read state of a task changed
The priority of a task changed
A task has been forwarded or rejected
A widget has been initialized
A workspace has been closed
The theme has been changed
- The theme data is sent within the message
A rendition has been added to a document
A taxonomy has been selected
A dictionary has been selected
A user has been selected
A group has been selected
A relation has been selected
An audit has been selected
A distribution configuration has been selected
A workflow tracker has been selected
A workflow activity has been selected
A rendition has been selected
A retention has been selected
A markup has been selected
A search has been selected
A facet has been selected
A query form has been selected
The version of a VD has been bounded
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
NNOTATION
D2_ACTION_CONTENT_EDIT_NATIVE_ANNOTA
TION
D2_ACTION_COMMENT
D2_ACTION_CONTENT_CREATE
D2_ACTION_CONTENT_IMPORT
D2_ACTION_FOLDER_CREATE
D2_ACTION_OBJECT_DESTROY
D2_ACTION_DISTRIBUTION_ACCEPT
D2_ACTION_DISTRIBUTION_REJECT
D2_ACTION_DISTRIBUTION_PREPARE
D2_ACTION_DISTRIBUTION_LAUNCH
D2_ACTION_DISTRIBUTION_STOP
Request view of a document with native annotation
Parameters : oam_id as the id of the document to view
Request edit native annotation of a document
Parameters : oam_id as the id of the document to edit
Request display of the comment dialog
Parameters :
- oam_id as the id of the document to comment
- parentCommentId as the parent comment
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
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
Request display of the folder creation dialog
Parameters :
- root_object_type set to dm_folder or dm_cabinet
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
Accept the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name
Reject the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name
Prepare the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name
Launch the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name
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
D2_ACTION_LIFECYCLE_DCTM
D2_ACTION_PERMISSIONS_SHOW
D2_ACTION_ADVANCED_SEARCH
D2_ACTION_PREFERENCES_SHOW
D2_ACTION_QUERYFORM_SHOW
D2_ACTION_RENDITION_ADD
D2_ACTION_RENDITION_REQUEST
D2_ACTION_SYNCPLICITY
D2_ACTION_VD_ADD_CHILD_SELECTED
D2_ACTION_VD_REMOVE_CHILD_SELECTED
D2_ACTION_VD_SET_CHILD_BINDING_VERSI
ON
D2_ACTION_VD_INSERT_INHERITED_COMPON
ENT
D2_ACTION_VD_CLEAR_VD
D2_ACTION_WORKFLOW_LAUNCH
D2_ACTION_WORKFLOW_LAUNCH_SCHEDULE
D Parameters :oam_id as the queue_item
D2_ACTION_WORKFLOW_UPDATE_PERFORME
RS
D2_ACTION_WORKFLOW_ABORT
D2_ACTION_TASK_ACQUIRE
D2_ACTION_TASK_READ
D2_ACTION_TASK_PRIORITY
Report the distribution
Parameters :
- oam_id as the id of the object
- config_name as the distribution configuration name
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
Request display of the permissions dialog
Parameters : oam_id as the id of the object
Request display of the advanced search dialog
Request display of the user preferences dialog
Request display of the query form dialog
Parameters : oam_id as the id of the query form
Request display of the add rendition dialog
Parameters : oam_id as the id of the document to add rendition to
Request rendition for a document
Parameters : oam_id as the id of the document
Request display of the Syncplicity dialog for a document
Parameters : oam_id as the id of the document
Request display of the add child dialog for the current selected item in the
VD widget
Request display of the remove child dialog for the current selected item in
the VD widget
Request setting of binding version of the current selected item in the VD
widget
Request display of the inserted inherited component dialog for the current
selected item in the VD widget
Request the VD widget to clear its content
Launch a workflow for a document.
Parameters :
- oam_id as the id of the document
- config as the workflow configuration name to use
Launch a scheduled workflow for a document.
Request display of the update performers dialog
Parameters :oam_id as the queue_item
Request display of the abort workflow dialog
Parameters :oam_id as the tracker
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
Set the task as read/unread
Parameters :
- oam_id as the id of the task
- read if true, unread otherwise
Set the task priority
Parameters :
- oam_id as the id of the task
EMC Documentum D2 External Widgets 11

D2_ACTION_TASK_FORWARD
D2_ACTION_TASK_REJECT
D2_ACTION_TASK_DELEGATE
D2_ACTION_TASK_NOTE
D2_ACTION_TASK_PROCESS
D2_ACTION_TAXONOMY_EXPORT
D2_ACTION_TAXONOMY_IMPORT
D2_ACTION_TAXONOMY_CHECKIN
D2_ACTION_TAXONOMY_SAVE
D2_ACTION_TAXONOMY_PROPERTIES
D2_ACTION_TAXONOMY_LOCATE
D2_ACTION_TAXONOMY_RESTORE
D2_ACTION_DICTIONARY_EXPORT
D2_ACTION_DICTIONARY_IMPORT
D2_ACTION_DICTIONARY_SAVE
D2_ACTION_DICTIONARY_RESTORE
D2_ACTION_DICTIONARY_UPDATE
D2_ACTION_DICTIONARY_PROPERTIES
D2_ACTION_RELATION_CREATE
D2_ACTION_RELATION_DESTROY
D2_ACTION_MASS_UPDATE
- priority ( integer as string )
Request display of the task forward dialog
Parameters : oam_id as the id of the task
Request display of the task reject dialog
Parameters : oam_id as the id of the task
Request display of the task delegate dialog
Parameters :
- oam_id as the id of the task
- source : tracker or task
Request display of the task note dialog
Parameters : oam_id as the id of the task
Request display of the task process dialog
Parameters :
- oam_id as the id of the task
- operation to perform
Request display of the export taxonomy dialog
Parameters : oam_id as the id of the taxonomy
Request display of the import taxonomy dialog
Parameters : oam_id as the id of the taxonomy
Request display of the checkin taxonomy dialog
Parameters : oam_id as the id of the taxonomy
Request display of the save taxonomy dialog
Parameters : oam_id as the id of the taxonomy
Request display of the taxonomy properties dialog
Parameters : oam_id as the id of the taxonomy
Request locate of the taxonomy
Parameters : oam_id as the id of the taxonomy
Request display of the restore taxonomy dialog
Parameters : oam_id as the id of the taxonomy
Request display of the export dictionary dialog
Parameters : oam_id as the id of the dictionary
Request display of the import dictionary dialog
Parameters : oam_id as the id of the dictionary
Request display of the save dictionary dialog
Parameters : oam_id as the id of the dictionary
Request display of the restore dictionary dialog
Parameters : oam_id as the id of the dictionary
Request display of the update dictionary dialog
Parameters : oam_id as the id of the dictionary
Request display of the dictionary properties dialog
Parameters : oam_id as the id of the dictionary
Request display of the relation creation dialog
Parameters : oam_id as the id of the document to create a relation with
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
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