External widget in Documentum Client

Documentum Client supports displaying of external clients which are deployed in the same app server using the external widget configuration.

Admin can create widgets with widgettype as ExternalWidget and specify the path for the external client starting from the context. Details can be seen in the Documentum Client administration guide.

In Documentum Client, external widgets can be configured as part of the menu configuration with either as dynamic menus or as direct static menus. On selection of the menu items, external widget will be loaded in an iframe as a side panel.

External widget can also be configured as a tile in the landing page and on click of the tile, external widget will be loaded in an iframe as a side panel. Details can be seen in the Documentum Client administration guide under the landing page section.

External widgets are mainly used for the use cases where the widgets want to have a communication with the Documentum Client and vice versa. This is achieved using the library OpenAjaxManagedHub-all.js. In order to ease the usage of the library we have exposed a wrapper module called DCTM-OAH.js which will have easily understandable API for communication.

Both the libraries will be present under the following path

{D2SV-ROOT}/ui/OpenAjaxManagedHub-all.js

{D2SV-ROOT}/ui/DCTM-OAH.js

All the communication are driven through event mechanism which can be published/subriced to from the client

How to register external application with Documentum Client.

All the external widgets need to map the OpenAjaxManagedHub-all.js and DCTM-OAH.js as part of the html/jsp in the external widgets.

In order to communicate with Documentum Client, external application needs to register as a client to Documentum Client. This can be as follows

 dctmOpenAjaxHubClient = new DCTMOpenAjaxHub();
dctmOpenAjaxHubClient.connectHub(connectCompleted, onActiveWidget);

function connectCompleted(hubClient, success, error) {
 
}
function onActiveWidget(bActiveFlag) {
    
}

In the above code connectCompleted and onActiveWidget are callback methods triggered when the client is registered.

Subscription and publishing an event in External widget client

To listen to events performed in the Documentum Client, external widget can subscribe to the events . Similarly external widgets can publish an event which will be listened by Documentum Client and perform accordingly

All the messages that are published or subscribed will of OpenAjaxMessage type. This is a standardized JS object created to ease the usage of OAH.

Object details will be present in DCTM-OAH.js

How to subscribe an event

 dctmOpenAjaxHubClient.subscribeToChannels(sChannel, fCallbackDataReceived, bHandleMessageIfNotDisplayed);

In the above case sChannel will be array of events to listen to from documentum

Parameter	Type	Description
sChannel	Arrays of String	array of events to listen to from Documentum Client
fCallbackDataReceived	function	Callback function to be triggered when published from Documentum Client
bHandleMessageIfNotDisplayed	boolean	Boolean flag to be triggered to respond event if the widget is not visible

How to publish an event

    let msg = new OpenAjaxMessage();
    dctmOpenAjaxHubClient.sendMessage(sChannel, oMessage);

In the above case sChannel will be the event to publish

Parameter	Type	Description
sChannel	String	event name
oMessage	Object	OpenAjaxMessage object that will carry the necessary information to be published

Supported Events

Event	Details
D2_EVENT_SELECT_OBJECT	This is a subscribed event which will be published from Documentum Client whenever an object is selected. This will return the following information r_object_id as oma_id, type and aContentType
D2_EVENT_SELECT_OBJECTS	This is a subscribed event which will be published from Documentum Client whenever object/objects is selected.
D2_ACTION_DM_TICKET_GENERATE	This event is published to D2 to request for for a new DCTM ticket. Oonce the DCTM ticket is generated from Documentum Client, it will publish the ticket information under thew event D2_EVENT_DM_TICKET_GENERATED
D2_EVENT_DM_TICKET_GENERATED	This event will be published from Documentum Client whenever it geenrates a new ticket on request from external clients as part of event D2_EVENT_DM_TICKET_GENERATE
D2_ACTION_EXECUTE	This event is published to Documentum Client to execute a generic action services. It will require the following parameter as part of the message: eService, eMethod, rType, rAction
D2_EVENT_WIDGET_BEFORE_CLOSE	This event is published to external client widget to notify that the widget will be closed. This will allow external widget to perform some clean up before the widget is closed. External widget can do the cleanup and will need to publish an event D2_EVENT_WIDGET_CLOSE_OK to confirm the close action. This is used if the 'Synchronize widget close' is enabled in config
D2_EVENT_WIDGET_CLOSE_OK	This event is published from external widget to Documentum Client to confirm the close action after receiving the event D2_EVENT_WIDGET_BEFORE_CLOSE. This is used if the 'Synchronize widget close' is enabled in config
D2_EVENT_WIDGET_CLOSED	This event is published from Documentum Client to external widget to notify that the widget is closed.

Sample External Widget Application

Below is a sample external widget which has 2 file external.js and external.html. Create a folder external in app server and add these 2 files

external.html

<!DOCTYPE html>
<html lang="en">
<head>
    <script type="text/javascript" language="javascript" src="<replace with context to D2SV>/ui/OpenAjaxManagedHub-all.js"></script>
    <script type="text/javascript" language="javascript" src="<replace with context to D2SV>/ui/DCTM-OAH.js"></script>

    <script type="text/javascript" language="javascript" src="external.js"></script>
    <meta charset="UTF-8">

 <style>
        .button {
            align-items: center;
            border: none;
            border-radius: 16px;
            cursor: pointer;
            font-size: 14px;
            height: 32px;
            justify-content: center;
            min-width: 80px;
            padding: 0px 24px;
            white-space: nowrap;
            border: 1px solid #232e72;
            box-sizing: border-box;
            color:  #232e72
        }


        TABLE > THEAD {
            background-color: #eef2f4;
            height: 42px;
            line-height: 37px;
        }

        TABLE > TBODY > TR, TABLE > THEAD > TR{
            border-bottom-color: rgb(51, 51, 51);
            font-size: 13px;
        }
        TABLE > TBODY > TR > TD{
            color: #333333;
            font-size:13px

        }

        TEXTAREA{
           flex: 1 1 0;
            line-height: normal;
            text-align: left;
            border: 1px solid #a7a9ac;
            -moz-border-radius: 3px;
            -webkit-border-radius: 3px;
            border-radius: 3px;
            padding: 3px;
            width: 100%;
            max-height: 68px;
            height: 68px;
            padding-left: 0.5em;
        }


        body{
            font-family: "OpenText Sans", "Helvetica", "Arial", sans-serif;
        }

        div.header{
            background-color: #dce4e8;
            color: #333333;
            border-bottom: 1px solid #d5d5d5;
            width: 100%;
            height: 28px;
            text-align: center;
            vertical-align: middle;
            padding-top: 11px;
        }
    </style>
    <title>Title</title>
</head>
<body>
<div class="header">Documentum Client External Widget</div>
<table style="width:100%">
    <thead>
    <tr>
        <th style="width:30%">Subscribed Event</th>
        <th  style="width:70%">Event Response</th>
    </tr>
    </thead>
    <tbody id="eventDetailsBody"></tbody>
</table>

<button class="button" onclick="requestNewTicket()">generate ticket</button>
<button class="button" onclick="requestNewActionEvent()">Show Report Templates</button>
<button id="closeWIndow" class="button" style="display:none;" onclick="closeWindow()">Close window</button>
</body>
</html>

external.js

let svEvents = null;
let dctmOpenAjaxHubClient = null;
let isActive = false; // assume widget is invisible / out-of-focus until "D2_EVENT_WIDGET_DISPLAYED" event received



let initSVExternalWidget = () => {
    svEvents = [ "D2_EVENT_SELECT_OBJECT", "D2_EVENT_SELECT_OBJECTS", "D2_EVENT_DM_TICKET_GENERATED","D2_EVENT_WIDGET_BEFORE_CLOSE"];
    window.onload = function() {
        loadEventTable();
    };

    dctmOpenAjaxHubClient = new DCTMOpenAjaxHub();
    dctmOpenAjaxHubClient.connectHub(connectCompleted, onActiveWidget);
}

let connectCompleted = (hubClient, success, error) => {
    if (success) {
        console.log("Widget connected to D2 client hub.");
        dctmOpenAjaxHubClient.subscribeToChannels(svEvents, d2MessageHandler, true);
    } else {
        console.error("Widget unable to connect to D2 client hub.");
    }
}

// Widget activation callback
let onActiveWidget =  (bActiveFlag) => {
    console.info("Widget " + (bActiveFlag ? "loaded" : "unloaded") +
        " by D2: active=" + isActive + ", events=" + svEvents);
}

let d2MessageHandler = (event, message) => {
    if(event==='D2_EVENT_DM_TICKET_GENERATED'){
        loadTicketGenerated(message);
    }
    else if(event==='D2_EVENT_SELECT_OBJECT'){
        loadObjectSelection(message)
    }
    else if(event==="D2_EVENT_WIDGET_BEFORE_CLOSE"){
        document.getElementById(event).innerHTML= message;
        widgetCloseInitiated();
    }
    else{
        document.getElementById(event).innerHTML= message;
    }

}

let loadTicketGenerated = (message) => {
    let text = "";
    text+="ticket = "+message.get("ticket")+"\n";
    text+="ticket_timeout = "+message.get("ticket_timeout")+"\n";
    text+="ticket_time_generated = "+message.get("ticket_time_generated")+"\n";
    text+="ticket_time_expiration = "+message.get("ticket_time_expiration")+"\n";
    document.getElementById('D2_EVENT_DM_TICKET_GENERATED').innerHTML= text;
}

let loadObjectSelection = (message) => {
    let text = "";
    text+="id = "+message.get("oam_id")+"\n";
    text+="type = "+message.get("type")+"\n";
    text+="aContentType = "+message.get("aContentType")+"\n";
    document.getElementById('D2_EVENT_SELECT_OBJECT').innerHTML= text;
}


/**
 * This method is used to enable the close button
 **/
let widgetCloseInitiated= ()=>{
    document.getElementById("closeWIndow").style.display = "block";
}


/**
 * Method will remove the initiate of the external widget fro mhub
 **/
let closeWindow =()=>{
    var msg = new OpenAjaxMessage();
    msg.setGlobal(true);
    msg.put("source","ext");
    dctmOpenAjaxHubClient.sendMessage("D2_EVENT_WIDGET_CLOSE_OK", msg);
}


let requestNewTicket = () =>{
    let msg = new OpenAjaxMessage();
    msg.setGlobal(true);
    dctmOpenAjaxHubClient.sendMessage("D2_ACTION_DM_TICKET_GENERATE", msg);
}

let requestNewActionEvent = () => {
    let messageToSend = new OpenAjaxMessage();

    let queryFormConfigName = "QF DCTM-Reports Templates";

    // Specify a non-null ID (to pass request validation)
    messageToSend.put("oam_id", "");

    //In the message, we need to define what properties will be sent. Here r_object_type
    messageToSend.put("list", "r_object_type");

    //We set the r_object_type value
    messageToSend.put("r_object_type", 'tt_report');

    //set the query form config name which will be used to update the doclist
    messageToSend.put("config", queryFormConfigName);

    //Then we define what service and what method in the service will be called.
    //We call the Search service and the runQueryFormSearch method.
    //Calling this service will update the user's last search object
    messageToSend.put("eService", "Search");
    messageToSend.put("eMethod", "runQueryFormSearch");

    // When the service call completes, we can define an action to be executed. Here, an event will be posted.
    messageToSend.put("rType", "EVENT");

    // As the last search has been updated by the web service call, we will post
    //    the D2_ACTION_SEARCH_DOCUMENT event to display the search results
    messageToSend.put("rAction", "D2_ACTION_SEARCH_DOCUMENT::oam_id==lastSearch");

    //The message is now ready, it can be posted in the Hub
    dctmOpenAjaxHubClient.sendMessage("D2_ACTION_EXECUTE", messageToSend);
}

let loadEventTable = () =>{
    document.getElementById("eventDetailsBody").innerHTML="";
    for(let event of svEvents){
        var tr = document.createElement("tr");
        tr.innerHTML= "<td>"+event+"</td><td><textarea style='width:98%' id='"+event+"' rows='5'></textarea></td>";
        document.getElementById("eventDetailsBody").append(tr);
    }
}


/**
 *  Loading the sample DCTM external client with OAH.
 *
 * */

initSVExternalWidget();