Programming with the Finesse API

Transcription

1

2 Programming with the Finesse API

3 OpenSocial Gadgets Source:

4 OpenSocial Gadgets A gadget spec: Is an XML file Defines metadata about an OpenSocial app Is highly cacheable and does not need a high performance server Gadgets use existing web standards XML to define metadata HTML for markup JavaScript for interactivity CSS for presentation 4 4

5 Gadget Server A gadget server: Takes the gadget spec as input Performs optimizations on the gadget spec Outputs HTML, JavaScript, and CSS as one document 5 5

6 Gadget Container Displays the user interface Opens an IFrame to the rendered gadget 6 6

7 Gadget Spec Uses HTML to print Hello World Colors the text red with CSS <?xml version="1.0" encoding="utf-8"?> <Module> <ModulePrefs title="hello World!"> </ModulePrefs> <Content type="html"><![cdata[ <h1>hello World</h1> <style type="text/css"> h1 { color: #dd0000; } </style> ]]> </Content></Module> 7 7

8 Finesse Web Services Overview Source:

9 RESTful API s Representational State Transfer. Stateless, client-server, cacheable communications protocol Simple HTTP is used to make calls between machines. Web browsers can natively access REST APIs GET Retrieve the addressed object PUT Replace/modify the addressed object POST Create a new object DELETE Delete/destroy the addressed object 9

10 Finesse REST Objects User First name, last name State Teams Dialog Participants State Call Data Team Name Users 10

11 Sample REST Operations Change Agent State PUT /User/{id} <State>READY </State> Make Call POST /User/{id}/Dialogs <requestedaction>make_call</requestedaction> <fromaddress></fromaddress><toaddress></toaddress> Initiate Consult Call PUT /Dialogs/{id} <requestedaction>consult_call</requestedaction> <targetmediaaddress></targetmediaaddress><toaddress></toaddress> 11

12 Finesse Desktop Architecture Source:

13 High Level Architecture Client/Browser Finesse Notification Svc Database UI REST API UCCE Components PG CTI AW DB 13

14 Gadget & Container Division of Labor Gadget Container Handles identity and authentication Finesse Desktop Handles agent login Also takes care of opening/maintaining BOSH connection Gadget Mini application, self-encapulated Served from the same domain as container Requests to other domains are proxied 14

15 3 rd party Gadgets Finesse Client/Browser Gadget Finesse Server Gadget Container Proxy 3 rd Party Gadget Gadget XML Specification Web Services 15

16 Finesse Desktop Architecture Gadget Container BOSH Gadget OpenAjax (pubsub) Gadget API Finesse JS Library Abstracts interaction with Finesse API REST objects Eventing infrastructure Business Logic 16

17 Sample Request Flow Gadget Sends request to Finesse or other server Library For Finesse REST Objects, the library takes care of constructing the request and subscribing for notifications (where applicable) Takes care of requestid and asynchronous error notifications Container All requests are proxied by gadgets.io.makerequest 17

18 Sample Event Flow Container Recieves notification via BOSH Passes notification to OpenAjax Hub Library JavaScript REST Object is subscribed to OpenAjax topic JavaScript REST Object processes notification Updates internal data and notifies registered callbacks Gadget Business logic processes notifications as applicable 18

19 Demo Source:

20 Adding a CUIC Report to Finesse Source:

21 Cisco Unified Intelligence Center Example Here is what we want: 21

22 Step #1 Create a CUIC Permalink 1. Right-Click on the report 2. Select Edit Views 3. Copy the HTML Link 22

23 Step # 2 Create the Gadget 1. Open your favorite text editor and create a file called CUIC.xml 2. Replace the & in the permalink with & <?xml version="1.0" encoding="utf-8"?> <Module> My Gadget Title <ModulePrefs title="cisco Unified Intelligence Center Queue Data" height="300"> </ModulePrefs> <Content type="url" My Gadget Height The CUIC Permalink href=" r.htmx?viewid=6f1670b b a568c5a&linkt ype=htmltype&viewtype=grid" /> </Module> 23

24 Step # 3 Modify the layout file <layout> <role>supervisor</role> <page> <gadget> </page> <tabs> <tab> <id>home</id> Gadget Reference <label>home</label> <gadgets> <gadget> </gadgets> </tab> </role> </layout> </tabs> 24

25 Step # 4 Upload the Layout File 25

26 CUIC Example Architecture Gadget Server MyGadgetServer CUIC Report HTTP Fetch CUIC Report Cisco Finesse Server Web Gadget Services Container Fetch Gadget Fetch Report CUIC Report MyCUICServer Gadget Architecture enables client-side mashup & easier integration Gadget Upgrades handled by each server Reduces version compatibility dependencies 26

27 Creating a Sample Gadget Add the gadget to the Finesse container Set up the client services for the gadget Create a user object Utilize the GET/PUT methods of the user object Add a make call button Create a dialog object Utilize the GET methods of the dialog object Use the data of the dialog object to do a web search 27

28 Step 1: Download the Sample Gadget Download the sample gadget from CDN You should have the following files: -SampleGadget_Final.xml: Contains the final HTML for the gadget -SampleGadget_Final.js: Contains the final business logic/javascript for the gadget -SampleGadget.css: Contains the styling for the gadget -SampleGadget.xml: Contains the minimum HTML to make a gadget -SampleGadget.js: Contains the minimum business logic for a gadget -finesse.js: This file contains the Finesse javascript library Download jquery 1.5, the library uses jquery for some utility functions 28

29 Step 2: Hosting 3 rd party gadgets Finesse Server is a closed box. All 3 rd party gadgets (new gadgets that you develop) must be hosted on a separate web server. Ensure that this server is accessible by the Finesse servers. Finesse will render the gadgets as defined by the Layout XML The sample gadget will need to be hosted on a separate web server Place the following files (in the same folder) on your hosting web server: - SampleGadget.xml - SampleGadget.js - SampleGadget.css - finesse.js - jquery-1.5.min.js 29

30 Step 3: Adding the gadget to the Finesse Container The Finesse Layout XML defines the layout of the Finesse Desktop (both agents and supervisors), including the tab names and the gadgets shown on each tab. Tab names can appear in any language, as long as they are defined in the XML a) Use the Layout Settings gadget by logging into the Finesse Administration and clicking the Layout tab. This gadget allows the administrator to define/modify the layout of the Finesse Desktop for agents and supervisors. 30

31 Step 3: Adding the gadget to the Finesse Container b) In the Finesse Layout XML, add the url of the sample gadget (step 2) to the Agent section of the layout XML 31

32 Step 3: Adding the gadget to the Finesse Container d) Log into the Finesse Desktop as an Agent. You should see a blank sample gadget. 32

33 Step 4: Get the workspace ready The rest of this demo will explain step-by-step on how to add a user object, a dialog object, and make a call. The steps are broken down to be as simple as possible, so it may take many steps to see a usable gadget. The demo will pause at each task and it will require you to reupload the changed files to the hosted web server (if the files are being modified off of the server) as well as a logout and login of the agent to see the modifications. This step is optional and can be skipped. In this demo, the code to be added will be denoted by red font. Open up SampleGadget.xml and SampleGadget.js. These are the two files that we will be modifying. 33

34 Step 5: Initialize the ClientServices The ClientServices is a utility that sets up the BOSH connection and simplifies the construction of Finesse API requests and the consumption of Finesse events. The init function of the ClientServices require a configuration object that contains the properties used for making REST requests. This config object is already in the SampleGadget.js and does not need any modifications. finesse.gadget.config = (function () { var _prefs = new gadgets.prefs(); return { authorization: _prefs.getstring("authorization"), host: _prefs.getstring("host"), resthost: "localhost }; } ()); 34

35 Step 5: Initialize the ClientServices In SampleGadget.js, update the init function to initialize the ClientServices init : function () { gadgets.window.adjustheight(); // Initiate the ClientServices and load the user object. ClientServices are // initialized with a reference to the current configuration. finesse.clientservices.clientservices.init(finesse.gadget.config); } 35

36 Step 6a: Create User object This user object represents the user that is currently logged in. Function calls on this object only operate against this user. In SampleGadget.js, update the init function to add an instance of the User object var user; init : function () { finesse.clientservices.clientservices.init(finesse.gadget.config); user = new finesse.restservices.user({ id: id, onload : handleuserload, onchange : handleuserchange } } 36

37 Step 6b: Create User object In SampleGadget.js, create the callback functions from step 6a /** * Handler for the onload of a User object. This occurs when the User object is initially read * from the Finesse server. Any once only initialization should be done within this function. */ handleuserload = function (userevent) { }, /** * Handler for all User updates */ handleuserchange = function(userevent) { }, init : function () { } 37

38 Step 7: Add HTML DOM for the User GET This sample gadget will display the the user s id, first name, last name, role, extension, and it s current state. In this step, we are going to set up the gadget to have the ability to display the data. It will not populate the fields with user data. In SampleGadget.xml, add the following within the <body> tag: <body class="claro > <div> <fieldset id="userfieldset class="outline"> <legend>logged in as:</legend> <div><b> User ID: </b><span id="userid"></span></div> <div><b> First Name: </b><span id="firstname"></div> <div><b> Last Name: </b><span id="lastname"></div> <div><b> Role: </b><span id="userrole"></div> <div><b> Extension: </b><span id="extension"></div> <div><b> Current User State: </b><span id="userstate"></div> </fieldset> <br> </div> </body> 38

39 Step 8: Display User data using a GET This step will populate the fields from step 7 with user data. In SampleGadget.js, update the callback functions from step 6b render = function () { varcurrentstate = user.getstate(); // Examples of getting fields from the User object (GET) document.getelementbyid('userid').innerhtml = user.getid(); document.getelementbyid('firstname').innerhtml = user.getfirstname(); document.getelementbyid('lastname').innerhtml = user.getlastname(); if (user.hassupervisorrole()) { document.getelementbyid('userrole').innerhtml = 'Supervisor ; } else { document.getelementbyid('userrole').innerhtml = 'Agent'; } document.getelementbyid('extension').innerhtml = user.getextension(); document.getelementbyid('userstate').innerhtml = currentstate; gadgets.window.adjustheight(); }, handleuserload = function (userevent) { render(); }, handleuserchange = function(userevent) { 39

40 Step 9: Upload Gadget with User GET This step is optional. If you haven t already done so, log out the agent from the Finesse Desktop. Upload the SampleGadget.xml and SampleGadget.js to the hosted web server (Step 2). 40

41 Step 9: Upload Gadget with User GET Log into the Finesse Desktop and you should see: 41

42 Step 10: Add the User States User States is an enum of to maintain consistency amongst the code. This step is preparing the code for changing the user s state In SampleGadget.js, update the init function to add the user states var user, states; init = function() { finesse.clientservices.clientservices.init(finesse.gadget.config); user = new finesse.restservices.user({ id: id, onload : handleuserload, onchange : handleuserchange } states = finesse.restservices.user.states; }; 42

43 Step 11: Add HTML DOM for the User PUT Now, we will update the sample gadget to have two buttons. The first button changes the user to READY and the second changes the user to NOT_READY This step adds the visual piece of the User PUT, but the buttons will not function correctly. In SampleGadget.xml, add the following code: <fieldset id="userfieldset" class="outline"> <div><b> Current User State: </b><span id="userstate"></div> <br> <div id="goready"> <button onclick="finesse.modules.samplegadget.setuserstate('ready');">change state to READY</button> </div> <div id="gonotready"> <button onclick="finesse.modules.samplegadget.setuserstate('not_ready');">change state to NOT READY</button> </div> </fieldset> 43

44 Step 12: Add business logic for User PUT In this step, we are going to hook in the support for the button that was added in step 11. In SampleGadget.js, add a setuserstate function (matching the onclick of step 11) to the return clause. This function calls the user PUT method with the appropriate parameter. return { /** * Sets the user state */ setuserstate : function (state) { if (state === 'READY') { user.setstate(states.ready); } else if (state === 'NOT_READY') { user.setstate(states.not_ready); } }, }; 44

45 Step 12: Add business logic for User PUT In SampleGadget.js, update the render function to display/hide the correct button according to the user s current state: render = function () { document.getelementbyid('userstate').innerhtml = currentstate; // Example of setting the user state (PUT) if (currentstate === states.not_ready) { document.getelementbyid('goready').style.display = ""; document.getelementbyid('gonotready').style.display = "none"; } else if (currentstate === states.ready) { document.getelementbyid('gonotready').style.display = ""; document.getelementbyid('goready').style.display = "none ; } else { document.getelementbyid('gonotready').style.display = "none"; document.getelementbyid('goready').style.display = "none"; } gadgets.window.adjustheight(); }, 45

46 Step 13: Upload Gadget with User PUT Repeat Step 9 and you should see: 46

47 Troubleshooting Sanity Do the Finesse out-of-the-box gadgets work? Back to basics Does a sample/simple gadget run with only logging? Breakpoints Are the event handlers being triggered? Digging deeper Events Do you see the BOSH long poll return? Requests Manually construct the REST API request 47

48 Troubleshooting How to get server side logs Finesse logs can be obtained by using the CLI commands. The commands will prompt the user to specify a secure FTP server location to which the files will be downloaded. To use the CLI commands, SSH to the finesse box as the platform administrator user and type the following command depending on which logs you are trying to obtain: a) Desktop logs: file get activelog desktop recurs compress b) Platform Tomcat logs: file get activelog tomcat/logs recurs compress 48

49 Complete Your Online Session Evaluation Give us your feedback and you could win fabulous prizes. Winners announced daily. Receive 20 Passport points for each session evaluation you complete. Complete your session evaluation online now (open a browser through our wireless network to access our portal) or visit one of the Internet stations throughout the Convention Center. Don t forget to activate your Cisco Live Virtual account for access to all session material, communities, and on-demand and live activities throughout the year. Activate your account at the Cisco booth in the World of Solutions or visit 49

50 Final Thoughts Get hands-on experience with the Walk-in Labs located in World of Solutions, booth 1042 Come see demos of many key solutions and products in the main Cisco booth 2924 Visit after the event for updated PDFs, ondemand session videos, networking, and more! Follow Cisco Live! using social media: Facebook: Twitter: LinkedIn Group: 50

51