VIM Gadget Development - eGain 10/reference guides/vim gadget...VIM 10.1(1) Gadget Development...

18
The smarter way to manage customer contact Contact Exony +44 1635 271 5555 | [email protected] | www.exony.com | @exony_vim © Exony 2014 VIM Gadget Development EXONY-API-014 VIM 10.1(1) December 2014

Transcript of VIM Gadget Development - eGain 10/reference guides/vim gadget...VIM 10.1(1) Gadget Development...

The smarter way to manage customer contact

Contact Exony +44 1635 271 5555 | [email protected] | www.exony.com | @exony_vim © Exony 2014

VIM Gadget Development

EXONY-API-014

VIM 10.1(1)

December 2014

VIM 10.1(1) Gadget Development Guidelines Page 2

St Catherine's House, Oxford Square Oxford Street Newbury BERKSHIRE RG14 1JQ United Kingdom Tel: +44 1635 271555 Fax: +44 1635 271556 www.exony.com

Copyright Notice: This document has been prepared by Exony Limited and, subject to any existing rights of other parties; Exony is the owner of the copyright of this document. The contents or any part thereof may not be copied or disclosed to a third party without the written permission of Exony, nor may it be used for manufacturing or tendering purposes without the written permission of Exony.

Introduction

VIM 10.1(1) Gadget Development Guidelines Page 3

Introduction Virtualized Interaction Manager (VIM) is a private cloud management platform offering enterprise-class contact center consolidation, centralization and management. It is specifically designed for complex large-scale environments.

VIM provides a highly agile, virtualized software platform that lets you manage distributed data, operations, infrastructure and resources as a single entity across multiple time zones and languages. It is a smarter and simpler way to manage your contact center and maximize value in a multi-location, multi-channel world.

VIM offers flexible reporting and analytics, combining data from multiple sources to supply the right information and the right tools at the right time to managers, analysts and supervisors. This enables sharper decision-making and allows those decisions to be rapidly translated into actions to optimize and enhance customer experience and revenue generation.

The platform architecture offers secure separation of multi-tenant data, providing the right contact center resources to each department, site and line of business. VIM integrates with other tools like Workforce Management and Quality Management, enabling local managers to tap into the full capabilities of VIM and retain close control on the ground.

VIM provides full integration with the Cisco Unified CCE, UCM and CVP platforms, and consolidates data from other contact center platforms such as Avaya CMS to deliver an enterprise-wide view on performance.

What This Document Contains This document provides an overview of VIM’s framework for gadget development, a set of recommended best practices for developing gadgets consistent with other VIM gadgets and the specific steps required to upload new gadgets to the VIM repository.

Who Should Read This Document This document is intended for readers with a sound understanding of gadget development in an OpenSocial framework. It is not a generic introduction to gadget development. The prerequisites for gadget development in VIM are:

An understanding of the OpenSocial 0.8 specification

Basic to intermediate HTML and CSS skills

Intermediate JavaScript development skills

An understanding of the VIM Web Service APIs (see the VIM Web Services Reference for further information).

Any domain-specific knowledge required for developing your gadgets. For example to write a gadget that uses the VIM Web Service APIs to manage agents on Cisco CCE, you need an understanding of the Cisco concepts for agent creation (agent properties, agent team memberships, skill groups, precision queue attributes etc).

Introduction

VIM 10.1(1) Gadget Development Guidelines Page 4

Trademarks The terms Microsoft, Windows, Word, Excel, Reporting Services and Analysis Services are trademarks owned by Microsoft Corporation.

The terms Cisco, Unified ICM, Unified CC, Unified CCE, Unified CCH, CVP and CUCM are trademarks owned by Cisco Systems Inc.

Any terms used in this manual do not affect the validity of any trademark.

.

Table of Contents

VIM 10.1(1) Gadget Development Guidelines Page 5

Table of Contents 1 VIM OpenSocial Framework Overview ....................................................... 6 2 VIM Gadget Development Concepts ............................................................ 7

2.1 Gadgets ............................................................................................................... 7 2.2 Apps .................................................................................................................... 7

3 VIM Web Architecture and the OpenSocial Standard ............................... 8 4 VIM Gadget Layout ........................................................................................ 10

4.1 Gadget DOM Elements .................................................................................... 11 5 Supported OpenSocial APIs ......................................................................... 12

5.1 Gadget Prefs ..................................................................................................... 12 5.2 Gadget PubSub ................................................................................................. 13 5.3 Gadget Utils ...................................................................................................... 14 5.4 Gadget Windows.............................................................................................. 14

6 Reserved PubSub Event Keys ....................................................................... 15 7 Gadget Development Guidelines ................................................................ 16 8 Uploading Gadgets into the VIM Repository ............................................ 18

8.1 Production Gadgets ......................................................................................... 18 8.2 Gadgets Under Development ......................................................................... 18

Chapter 1: VIM OpenSocial Framework Overview

VIM 10.1(1) Gadget Development Guidelines Page 6

1 VIM OpenSocial Framework Overview The Exony VIM web application is built using the OpenSocial 0.8 standard, which defines a Web 2.0 component model for a business application focused browser based environment.

Each gadget can communicate with other gadgets in the browser page by means of publishing or subscribing to events, which are handled entirely in the browser. The use of the OpenSocial standard coupled with VIM REST services gives a rich interactive experience for the user. This standard allows customers and partners to add their own gadget content to the VIM application. By combining a gadget interface component with VIM’s Web Service APIs, or with functionality from relevant third party applications, VIM can be extended to deliver additional capabilities and business value for enterprises.

Note that although OpenSocial 0.8 is a web standard, gadgets developed for other vendors’ frameworks may not work in VIM so developers should ensure that gadgets intended for use in VIM are qualified against the target VIM deployment environment.

Chapter 2: VIM Gadget Development Concepts

VIM 10.1(1) Gadget Development Guidelines Page 7

2 VIM Gadget Development Concepts

2.1 Gadgets Gadgets are web 2.0 components made up of HTML DOM elements, CSS, and JavaScript. Typically a gadget will be designed to fulfill a particular business function such as managing a contact center agent or running a report. Gadgets can work in conjunction with other gadgets, for example a navigation or search gadget can be used to select items for a separate gadget to perform updates on. These gadgets are rendered in a browser using content generated by an OpenSocial Container on the server, which is user and security aware.

2.2 Apps In the VIM application one or more OpenSocial gadgets are collected together into an app. For example, a contact center app may implement a typical agent desktop which contains tools to receive and process inbound and outbound customer contacts.

Multiple apps can be created by the VIM user or the VIM service provider to support different roles. For example, an inbound agent app may contain gadgets for call management and queue information while an inbound supervisor app may also contain gadgets for agent management.

Gadgets and apps are standard VIM resources and have the same role-based security as the rest of the platform. A VIM user can specify a default app, which automatically loads on their home page when they log in.

Chapter 3: VIM Web Architecture and the OpenSocial

Standard

VIM 10.1(1) Gadget Development Guidelines Page 8

3 VIM Web Architecture and the OpenSocial Standard This section provides an overview of how gadgets interact with the VIM application stack.

This diagram shows the VIM implementation of the OpenSocial standards based architecture and the key data flows between the client browser and the VIM server.

Figure 1 Exony OpenSocial Architecture Implementation

Note

Supported browsers and versions are:

Internet Explorer version 8 or later

Google Chrome version 25 or later

Mozilla Firefox version 18 or later.

1. Desktop and App Page Load. When a user connects to the VIM web application using a supported browser, and is successfully logged in, their default app is downloaded from the web server. The default app is typically something defined by the end user for a specific purpose (for example,

Chapter 3: VIM Web Architecture and the OpenSocial

Standard

VIM 10.1(1) Gadget Development Guidelines Page 9

supervisor inbound team management), and will contain one or more gadgets.

2. Render Gadget. The browser renders the app, which requests the OpenSocial Container on the VIM server to render each gadget and return its content for display in a per gadget iFrame.

3. Read App and Gadget Definitions. The OpenSocial Container loads each gadget from the gadget repository. Then the OpenSocial Container reads the gadget metadata header to determine the correct server side processing actions, for example, performing language translations or adding in the specified OpenSocial features. This load and server render process can be slow for complex gadgets and so once a gadget has been rendered, it is cached in the server for a period to reduce the load on server. This means that the application can cope with periods of peak activity such as shift changes when large numbers of users log in within a short timeframe.

4. Business Logic Interactions. The rendered server content for each gadget is returned to the browser which injects it into an iFrame dedicated to that gadget instance. The user can then interact with the gadget, which may request additional data or services from the server. On the client side the active gadget code running in the iFrame communicates back to the VIM server using REST web services and can communicate with other gadgets using the OpenSocial PubSub standard.

Chapter 4: VIM Gadget Layout

VIM 10.1(1) Gadget Development Guidelines Page 10

4 VIM Gadget Layout An OpenSocial gadget is specified in an XML document that has two sections:

The header section, within the <ModulePrefs> tags, defines the metadata used by the OpenSocial Container to provide the server side rendering characteristics.

The content section, within the <Content> tags, defines the gadget user interface and client-side business logic. It consists of HTML DOM elements, CSS and JavaScript.

An example gadget skeleton is shown below.

VIM Gadget Skeleton <?xml version="1.0" encoding="utf-8"?> <Module> <ModulePrefs title="Resource Manager" description="The provisioning gadget for provisioning contact centre resources"> <Require feature="pubsub-2" /> <Require feature="setprefs" /> <Require feature="settitle" /> <Locale lang="fr" country="CA" messages="https://localhost/Portal/gadgets/msgs/GadgetsI18n_fr_CA.g.xml" /> <Locale lang="fr" messages="https://localhost/Portal/gadgets/msgs/GadgetsI18n_fr_ALL.g.xml" /> <Locale messages="https://localhost/Portal/gadgets/msgs/GadgetsI18n_ALL_ALL.g.xml" /> </ModulePrefs> <Content type="html"> <![CDATA[

<-- JavaScript Includes --> <-- CSS Includes --> <-- DOM Elements -->

]]> </Content>

</Module>

This example skeleton contains sufficient information for the OpenSocial Container to determine what actions are needed to process the gadget. Items of interest are:

title - the title of the gadget as displayed on the gadget title bar

Require - which OpenSocial features are needed for the OpenSocial Container to render this gadget

pubsub-2 - the inter-gadget communication mechanism.

setprefs – store the individual user preferences for a user for this gadget on the client.

settitle – used when the gadget needs to change the title at runtime.

Chapter 4: VIM Gadget Layout

VIM 10.1(1) Gadget Development Guidelines Page 11

Locale - Message bundles that contain the translations used either by server side ${Msg.Dimensions.CALL_TYPE} or client side prefs.getMsg.

Content - VIM only supports type=”html”. The gadget application elements are contained between the CDATA opening and closing tags.

4.1 Gadget DOM Elements This section shows example HTML DOM elements operated upon by the JavaScript objects.

The example shows:

a spinner div (id=spinnerId) that is used by the main View to show the gadget is busy

an anchor for a resource grid div (id=resourceGridDiv) that can be used to inject a jqGrid with VIM resource detail

DOM Elements Example <div id="spinnerId" style="text-align:center;padding-top:25px"> <img src="CoreImages/large_spinner.gif" alt="${Msg.GeneralText.LoadingDotDotDot}" /> </div> <div id="resourcesGridDiv" class="table table-striped"> <table id="resourcesGrid" class="table table-striped"></table> <div id="pager"></div> </div>

Chapter 5: Supported OpenSocial APIs

VIM 10.1(1) Gadget Development Guidelines Page 12

5 Supported OpenSocial APIs This section describes the supported client side OpenSocial APIs which are available at run-time.

5.1 Gadget Prefs This OpenSocial API provides access to two core OpenSocial functions:

the internationalized messages (as set by the user login context).

the user preferences, if the OpenSocial setprefs feature has been set in the gadget ModulePrefs section.

Note

Preferences data is stored in the browser session and is persisted to VIM if the user has Manage Apps permission. Unless the user saves the App, preferences data will not persist across VIM user login sessions.

The following OpenSocial Gadget Prefs APIs are supported:

API Description

gadgets.prefs.getBool (key) Returns a preference as a boolean or false if not set.

gadgets.prefs.getCountry() Retrieve the current country as ISO 3166-1 alpha-2 code

gadgets.prefs.getFloat (key) Retrieves a preference as a float.

gadgets.prefs.getInt (key) Retrieves a preference as an integer or 0 if not set.

gadgets.prefs.getLang() Returns the current language the gadget should use when rendering, returned as a ISO 639-1 language code

gadgets.prefs.getModuleId() Returns the module id for the current gadget instance. Currently always 0.

gadgets.prefs.getMsg(key) Retrieves an unformatted message

gadgets.prefs.getString(key) Retrieves a preference as a string

gadgets.prefs.Set(key, val) Stores a preference. To use this call, the gadget must require the feature setprefs.

The storage of gadget preferences is typically made using the gadgets.prefs.Set API serialized as a JSON string and retrieved on startup using the gadgets.Prefs.getString Method.

Chapter 5: Supported OpenSocial APIs

VIM 10.1(1) Gadget Development Guidelines Page 13

Gadget Prefs Example // Get I18N value of "Folder" for the current locale. var prefs = new gadgets.Prefs(); var folderMsg = gadgets.Prefs.getMsg("GeneralText.Folder");

5.2 Gadget PubSub VIM implements the OpenSocial pubsub-2 gadget communication feature. It allows gadgets to publish events and subscribe to events in order to improve user interactivity with the application. Each event is given a strict namespace to avoid collisions (see section 6 for details). In OpenSocial these namespaces are known as topics. Publishers send messages to topics and subscribers receive messages on those topics.

The following APIs are supported: API Description

gadgets.Hub.publish ("topic", "message")

Any kind of object may be published provided it is serializable to JSON.

gadgets.Hub.subscribe ("topic", callback)

This method indicates to the hub the topic that the gadget is interested in receiving information about.

gadgets.Hub.unsubscribe("topic") Remove a subscription for a gadget from the hub

This example shows sample publisher and subscriber code.

PubSub Example // Publisher: // Publish the selection to any subscribers who have registered an interest in a resource of this type. var resourceKey = { id: resourceId, type: resourceType, folderId: folderId }; gadgets.Hub.publish("exony.resource.selected", resourceKey); // Subscriber: // Register interest in a resource of this type. var resourceKey = { id: resourceId, type: resourceType, folderId: folderId }; gadgets.Hub.subscribe("exony.resource.selected", function(resourceKey){ // Process the supplied resource key

});

Chapter 5: Supported OpenSocial APIs

VIM 10.1(1) Gadget Development Guidelines Page 14

5.3 Gadget Utils VIM supports a partial implementation of the OpenSocial Utils API.

The following API is supported:

API Description

gadgets.util.registerOnLoadHandler (callback)

Registers an on-load handler (a function that executes when the gadget loads). Multiple handlers can be registered, and all will be invoked, in the order in which they were registered.

This example removes the padding from the body HTML once the gadget has loaded.

Utils Example // Remove padding from body after gadget load

gadgets.util.registerOnLoadHandler(function () { $j('body').css("padding", "0"); });

5.4 Gadget Windows VIM allows a gadget to obtain information about the window the gadget is located in and to modify the window properties.

The following APIs are supported:

API Description

gadgets.window.setTitle(title) Implementation of the OpenSocial settitle feature. The API sets the gadget title

gadgets.window.adjustHeight (opt_height)

Adjusts the gadget height.

gadgets.window. getViewportDimensions

Detects the inner dimensions of the frame and returns an object with the width and height.

This example sets the height of the gadget.

Gadget Windows Example // Set gadget window height var heightVal = 500; gadgets.window.adjustHeight(heightVal);

Chapter 6: Reserved PubSub Event Keys

VIM 10.1(1) Gadget Development Guidelines Page 15

6 Reserved PubSub Event Keys This page details the reserved PubSub event keys that are used by the platform.

Key Description Address Requirements

exony.resource.selected Raised when a resource item is selected to allow subscribing gadgets to be loaded.

{id:12345, type:IT_Agent}

exony.finesse.xmppActive Used by the Exony framework to signal when the Finesse XMPP connection has been established

true/ false

exony.finesse.logout Fired when a logout is performed from within the Exony framework

true

exony.finesse.logon Used by the Exony framework to signal a Finesse logon and establish a BOSH connection to the XMPP Service

{extension:12345, password:XXXX}

finesse.* Reserved for conversion of events raised from the Finesse XMPP Service

exony.gadgets.enablerefresh.* Reserved by the container for the exony.refresh feature. Keys will contain the index of the container on the page e.g. exony.gadgets.enablerefresh.4

true/ false

exony.gadgets.window.* Reserved by the container for communication between the gadget and the container for resize events contained in the gadgets.window class. Keys will contain the index of the container on the page e.g. exony.gadgets.window.4

{title: "THE GADGET TITLE"}

Chapter 7: Gadget Development Guidelines

VIM 10.1(1) Gadget Development Guidelines Page 16

7 Gadget Development Guidelines This section contains guidelines for gadget development for the VIM platform. It is recommended that you follow these guidelines where possible.

Cross Browser Support

VIM supports the Internet Explorer, Firefox and Chrome browsers. Gadget developers should ensure that gadgets developed for VIM are compatible with these browsers.

Note

Supported browsers and versions are:

Internet Explorer version 8 or later

Google Chrome version 25 or later

Mozilla Firefox version 18 or later.

Consuming 3rd Party REST APIs

When accessing 3rd party APIs from gadgets within the VIM framework, the Web Service calls must be reverse proxied on the VIM Web Server, or on an external reverse proxy appliance to avoid the same-origin problem. Same-origin policies restrict how a document or script from one site interacts with a resource from another origin.

Inter-gadget Communication

VIM gadgets should use the OpenSocial PubSub APIs as the inter-gadget communication mechanism, for example: gadgets.Hub.publish("exony.resource.selected", resourceKey);

Note

OpenAjax is used as the implementation mechanism for PubSub.

Consuming Cisco Finesse Events

VIM gadgets can consume Cisco BOSH notifications for Cisco Finesse events. These are implemented on the Finesse server as XMPP notifications, consumed by the VIM client side framework and translated/published to the gadgets as OpenSocial PubSub events.

Internationalization

VIM gadgets can be internationalized using one of the following:

Server side translation using the in-line gadget translations. Typically around DOM elements, for example ${Msg.Dimensions.CALL_TYPE}.

Chapter 7: Gadget Development Guidelines

VIM 10.1(1) Gadget Development Guidelines Page 17

Note

This is not translated in included JavaScript files and these must use the client prefs API.

Client side OpenSocial prefs API for localization in the gadget JavaScript, for example prefs.getMsg('GeneralText.FirstName').

Chapter 8: Uploading Gadgets into the VIM Repository

VIM 10.1(1) Gadget Development Guidelines Page 18

8 Uploading Gadgets into the VIM Repository

8.1 Production Gadgets When a gadget is ready for use, it is uploaded into the VIM repository using Settings > Gadget Management (see the VIM User Guide for more information). Different gadgets can be stored in different folders in VIM allowing different gadgets and apps to be offered to different groups of users.

8.2 Gadgets Under Development While a gadget is under development, you can avoid having to repeatedly upload the latest gadget code to VIM for testing as follows:

1. When you develop the gadget and upload the gadget code to VIM for the first time, ensure that the specified gadget name matches the gadget file name.

2. On the VIM Database Server, start the ICE tool and select System Properties.

3. In the Gadget Management group, set:

Gadgets Cache Expiration Period to 0

Gadgets File Path to the folder on the VIM Web Server where the gadget file is stored.

When the gadget is rendered the OpenSocial Container will load the gadget definition directly from the specified gadget file path instead of using the cached version.

Note

To avoid multiple web servers rendering different gadget versions, do not set Gadgets Cache Expiration Period to 0 on production servers.