Professional Services. Desktop Wallboard. Programmer Guide. Release Avaya Inc. Proprietary Use Pursuant to Company Instructions

Transcription

1 Professional Services Desktop Wallboard Programmer Guide Release Avaya Inc. Proprietary Use Pursuant to Company Instructions

2 Copyright 2016 Avaya Inc. All Rights Reserved Printed in USA Notice While reasonable efforts were made to insure that the information in this document was complete and accurate at the time of printing, Avaya Inc. can assume no liability for any errors. Changes and corrections to the information in this document may be incorporated in future releases. Trademarks Adobe, Adobe Acrobat, and the Adobe logos are registered trademarks of Adobe Systems Inc. DEFINITY and the Avaya Inc. logotype are registered trademarks of Avaya Inc. Microsoft, DOS, and Windows are registered trademarks of Microsoft. All products and company names are trademarks or registered trademarks of their respective holders. Obtaining Products To learn more about Avaya Inc. products and services, access the Avaya web site Acknowledgement This document was prepared by Avaya Inc. Professional Services 1111 Freeport Parkway Coppell, TX

3 TABLE OF CONTENTS 1.0 OVERVIEW SYSTEM ARCHITECTURE ACTIVEX CONTROL ACCESSING THE CONTROL IN THE VISUAL BASIC IDE METHODS ADJUSTSPEED() ADJUSTSPEEDEX() ALIGNDATALEFT() BRINGWINDOWTOFRONT() CONNECT() DISCONNECT() GETMARQUEEDIRECTION() GETMARQUEESPEED() ISCONNECTED() VIEWCMSDATA() VIEWMESSAGES() VIEWOADATA() WRITETOLOG() EVENTS CMSMARQUEELOADED CMSMARQUEEUNLOADED CONFIGLOADED CONNECTED CUSTOMMARQUEELOADED CUSTOMMARQUEEUNLOADED DISCONNECTED ERROR MESSAGEMARQUEELOADED MESSAGEMARQUEEUNLOADED OAMARQUEELOADED OAMARQUEEUNLOADED RESIZED PROPERTIES DOCKEDEDGE ENCODING ISALWAYSONTOP ISDOCKED ISEXITENABLED ISLOGGINGENABLED SERVERIP SERVERPORT USERNAME ENUMERATIONS & TYPES ENCODINGTYPES Avaya Professional Services Page i

4 7.2 LOGGINGCATEGORY MARQUEESTATUS MARQUEETYPE SCREENEDGE SROLLDIRECTION SCROLLSPEED APPENDIX A - TROUBLESHOOTING APPENDIX B - LIST OF ACRONYMS Avaya Professional Services Page ii

5 LIST OF FIGURES Figure 1: DW Marquee Display... 1 Figure 2: System Architecture... 2 Figure 3: VB IDE New Project Dialog... 3 Figure 4: VB IDE Components Menu Item... 4 Figure 5: VB IDE Components Dialog... 5 Figure 6: VB IDE Components Dialog (2)... 5 Figure 7: VB IDE Component Toolbox... 6 Figure 8: DW Marquee Marquee Speed Dialog... 7 Figure 9: Current CMS Items Dialog Figure 10: Current Message Display Figure 11: Current OA Item Display Avaya Professional Services Page iii

6 LIST OF TABLES Table 1: Appendix A - Troubleshooting Table 2: Appendix B - Acronyms Avaya Professional Services Page iv

7 1.0 Overview Desktop Wallboard (DW) is a reporting solution that empowers agents by keeping them informed of contact center performance levels, bulletins, and instant notifications from administrators. The DW desktop solution features multiple scrolling marquees working together (Figure 1: DW Marquee Display) to display dynamic information gathered from multiple sources including Avaya Call Management System, Avaya Operational Analyst, and the DW database. Note: CMS and OA marquees are dependant on the optional CMS and OA server-side connector components. Figure 1: DW Marquee Display The CMS marquee provides agents with a data feed from the Call Management System (CMS). Data is retrieved directly from the CMS server through three near real-time custom reports (Agent, Skill, and VDN). As the reports are run, their output is pushed from the CMS to the DW server where it is stored in memory within the CMS Real-Time Collector service. Individual CMS marquees pull data from the DW server based on the CMS item configuration for the DW group that the agent belongs too. As the data is pulled from the DW server, it is checked against any configured thresholds that may exist. If the data exceeds a configured threshold, special threshold processing takes place. The OA marquee provides agents with a data feed from Operational Analyst (OA). OA data is retrieved from the OA server through the OA Data Export API. The DE API is used to setup a series of queries that are run against the Agent State, Agent Service Class, Service Class, and Service Class Summary tables. As the queries are run, their output is retrieved by the OA Real- Time Collector service and stored in memory. Individual OA marquees pull data from the DW server based on the OA item configuration for the DW group that the agent belongs too. As the data is pulled from the DW server, it is checked against any configured thresholds that may exist. If the data exceeds a configured threshold, special threshold processing takes place. The Message marquee provides a scrolling list of bulletins sent to agents by administrators. Bulletins are created using the web-based administration application, and they are stored within the DW database. The Message service is responsible for managing bulletins and pushing them to connected recipients. Additionally, agents can be sent instant notifications. Instant notifications are brief textual messages that are created through the web-based administration application. Instant notifications are sent directly to individual agents and are displayed as pop-up windows in the foreground of the agents desktop. Instant notifications are not stored within the system. Avaya Professional Services Page 1

8 2.0 System Architecture The following diagram depicts the Desktop Wallboard system architecture. Call Management System (CMS) Operational Analyst (OA) Data Export Servlet CLINT (Agent Report - Real Time) CLINT (Skill Report - Real Time) CLINT (VDN Report - Real Time) Time Table (Agent Report - Historical) Time Table (Skill Report - Historical) Time Table (VDN Report - Historical) RT-DSI HT-DSI TCP/IP HTTP/HTTPS Desktop Wallboard Server OA Real-Time Collector ADO.NET CMS Real-Time Collector ADO.NET.NET Remoting Database ADO.NET Message Server ADO.NET COM Interop DSI Web-Based Aministration (req. IIS &.NET Framework).NET Remoting Client Gateway HTTP TCP/IP LAN Workstation Workstation Workstation Workstation Figure 2: System Architecture Avaya Professional Services Page 2

9 3.0 ActiveX Control The core logic of the DW Marquee client application is contained in the ActiveX control DWMarqueeCtrl.ocx. The DW ActiveX control is available for use by integrators who want to include DW functionality in their custom software solutions. This document covers the properties and methods of the DW ActiveX control that integrators need to be familiar with in order to successfully incorporate DW functionality into custom software solutions. Note: Use of the DW administration web site, even in custom solutions, as it is the only mechanism for configuring the DW system. Note: All examples in this document were created in Visual Basic Accessing the Control in the Visual Basic IDE The following steps discuss how to access the DW Marquee ActiveX control from the Visual Basic 6 IDE. 1. Start Visual Basic 2. Open a new or existing project. Figure 3: VB IDE New Project Dialog Avaya Professional Services Page 3

10 3. Select Project Components This will bring up the Components dialog. Figure 4: VB IDE Components Menu Item Avaya Professional Services Page 4

11 Figure 5: VB IDE Components Dialog 4. Scroll down to Avaya Desktop Wallboard Marquee Control 4.0 and select it. Figure 6: VB IDE Components Dialog (2) 5. Select OK to apply the change an dismiss the dialog. Avaya Professional Services Page 5

12 6. The control should now be available in the Component Toolbox. Desktop Wallboard Marquee Control Figure 7: VB IDE Component Toolbox Note: When working with the ActiveX control you have direct responsibility for the visual width of the control, but you cannot change the visual height. The height of the control is dynamically managed based on the contents of the marquee. Avaya Professional Services Page 6

13 4.0 Methods 4.1 AdjustSpeed() DWMarquee.AdjustSpeed This function is used to display an embedded form for controlling the scroll speed of the marquee lines. This form can also be used to adjust the scrolling direction of the marquee. Figure 8: DW Marquee Marquee Speed Dialog Note: The lines available on the speed dialog are directly related to how the DW system is configured. For example, if the DW system does not include the optional CMS component, the CMS line will not be available in the speed dialog. Return Value: Example: This example shows how to allow the local user to adjust their marquee speed/direction by using a menu option created through the Visual Basic menu editor. Avaya Professional Services Page 7

14 Use a menu option to adjust the marquee speed/direction. Private Sub mnumarqueespeed_click() DWMarquee1.AdjustMarqueeSpeed End Sub DWMarquee.AdjustSpeedEx 4.2 AdjustSpeedEx() This function is used to programmatically adjust the speed of individual marquee lines Marquee A type definition that indicates which specific marquee to adjust (ex. CMS_MARQUEE, MESSAGE_MARQUEE, etc). Speed An enumeration that indicates the speed at which the marquee should scroll. Direction An enumeration that indicates which direction the specific marquee should scroll. Return Value: Example: Private Sub ChangeCMSSpeed DWMarquee1.AdjustMarqueeSpeedEx CMS_MARQUEE, MEDIUM, LEFT_TO_RIGHT End Sub 4.3 AlignDataLeft() DWMarquee.AlignDataLeft Avaya Professional Services Page 8

15 This function causes any data displayed in the marquee to reset itself with the leading edge of the first character aligned to the left edge of the marquee display. Return Value: Example: This example shows how to use a menu option to allow the user to left justify the data streams of the marquee. Align the marquees to the left margin. Private Sub mnurealign_click() DWMarquee1.AlignDataLeft End Sub DWMarquee.BringWindowToFront 4.4 BringWindowToFront() This function causes the marquee to be brought to the front of the Z-Order on the desktop. Return Value: Example: Pop the marquee to the front of other applications. Avaya Professional Services Page 9

16 Private Sub cmdpopmarquee_click() DWMarquee1.BringWindowToFront End Sub 4.5 Connect() DWMarquee.Connect ( ServerIP As String, ServerPort as Integer, Username as String, [UserPass as String] ) This function initiates an attempt to open a socket connection to the DW server. ServerIP as String This represents the IP address or hostname of the Desktop Wallboard server. ServerPort as Integer This represents the port number that the DW server is listening too for client connections. Username as String This is the users unique Desktop Wallboard username. UserPass as String (Optional) This is the users password as defined within the DW system. Return Value: MarqueeStatus.STATUS_OK on success. Note: Receiving STATUS_OK does not mean that you are connected to the server. It simply means that the action of opening the TCP socket and sending the connection request to the server were successful. Successfully completing the connection (being approved by the server) results in a Connected() event being raised on the marquee control. Example: This code shows an example of how to set up a connection request to the DW server. If the request fails, the example will check the type of error and display a message box as a result. Dim status As MarqueeStatus Dim serverip As String Avaya Professional Services Page 10

17 Dim serverport As Integer Dim username As String Dim userpass As String serverip = serverport = 5501 username = jdoe userpass = Start the marquee. status = DWMarquee1.Connect(serverIP, serverport, username, userpass) If (status <> STATUS_OK) Then If (status = STATUS_ERR_MISSING_REQUIRED_DATA) Then MsgBox Missing required data. Else MsgBox Failed to open the socket connection. End If End If DWMarquee.Disconnect 4.6 Disconnect() This function causes the marquee to terminate its connection with the DW server. Return Value: MarqueeStatus.STATUS_OK on success. Example: The following code snippet shows an example of how to shutdown the marquee from a host application. Notice the calls to IsConnected(). This function is used to determine if the marquee is actively connected to the server. Private Sub Form_QueryUnload(Cancel As Integer, UnloadMode As Integer) Cancel = True Avaya Professional Services Page 11

18 ' The only difference here is that if Windows is shutting down we don't prompt the user about whether they're ' sure they want to exit or not. If (UnloadMode = vbappwindows) Then If (DWMarquee1.IsConnected) Then DWMarquee1.Disconnect Cancel = False Else If (DWMarquee1.IsExitEnabled) Then If MsgBox( Are you sure you want to exit? ) = vbyes Then If (DWMarquee1.IsConnected) Then DWMarquee1.Disconnect Cancel = False End If End If End If End Sub 4.7 GetMarqueeDirection() DWMarquee.GetMarqueeDirection(marquee As MarqueeType) As ScrollDirection This function returns the ScrollDirection value for the specified marquee. Marquee The specific marquee type to query. Return Value: This function will return a value of type ScrollDirection indicating the direction that the specific marquee is scrolling. Example: Debug.Print DWMarquee1.GetMarqueeDirection(CMS_MARQUEE) 4.8 GetMarqueeSpeed() DWMarquee.GetMarqueeSpeed(marquee As MarqueeType) As ScrollSpeed Avaya Professional Services Page 12

19 This function returns the ScrollSpeed value for the specified marquee. Marquee The specific marquee type to query. Return Value: This function will return a value of type ScrollSpeed indicating the speed that the specific marquee is scrolling. Example: Debug.Print DWMarquee1.GetMarqueeSpeed(CMS_MARQUEE) DWMarquee.IsConnected 4.9 IsConnected() This function is called to determine if the marquee is actively connected to the Desktop Wallboard server. Return Value: A Boolean value indicating True if connected, False otherwise. Example: Check the connection status. Private Sub cmdcheckconnection_click() If DWMarquee1.IsConnected Then MsgBox We re connected! Else MsgBox We re not connected. Avaya Professional Services Page 13

20 End If End Sub 4.10 ViewCMSData() DWMarquee.ViewCMSData Calling this function will display the embedded CMS item dialog. Figure 9: Current CMS Items Dialog Return Value: Example: Avaya Professional Services Page 14

21 Pop the CMS item display. Private Sub cmdpopcmsdisplay_click() DWMarquee1.ViewCMSData End Sub DWMarquee.ViewMessages 4.11 ViewMessages() Calling this function will display the embedded message dialog. Figure 10: Current Message Display Return Value: Example: Pop the message display. Private Sub cmdpopmsgdisplay_click() DWMarquee1.ViewMessages End Sub 4.12 ViewOAData() Avaya Professional Services Page 15

22 DWMarquee.ViewOAData Calling this function will display the embedded OA item dialog. Figure 11: Current OA Item Display Return Value: Example: Pop the OA item display. Private Sub cmdpopoadisplay_click() DWMarquee1.ViewOAData End Sub 4.13 WriteToLog() DWMarquee.WriteToLog (msg As String, cat as LoggingCategory) Avaya Professional Services Page 16

23 This function is used to write a string to the log file. For this function to work logging must be enabled by setting the LoggingEnabled flag to 1 in the registry under HKEY_LOCAL_MACHINE\SOFTWARE\Avaya\DSI. msg as String Any string value. cat as LoggingCategory This enumeration represents the log level at which the string should be written (ex. LC_ERROR). Return Value: Example: Write an entry to the log file. Private Sub cmdwritetimestamp_click() DWMarquee1.WriteToLog Now, LoggingCategory.LC_INFO End Sub Avaya Professional Services Page 17

24 5.0 Events 5.1 CMSMarqueeLoaded This event is raised when the CMS-specific line within the OCX is created. 5.2 CMSMarqueeUnloaded This event is raised when the CMS-specific line within the OCX is removed. 5.3 ConfigLoaded This event is raised any time a new configuration is received from the server such as when the marquee is first started. In addition, any time an administrator makes a change to the configuration of a group all actively connected members of the group will receive the update, which in turn will fire this event on the control. 5.4 Connected This event is fired when the marquee receives a response from the DW server that it has been properly authenticated and is now ready to receive data. Avaya Professional Services Page 18

25 5.5 CustomMarqueeLoaded This event is not used. It is for future development. N/A 5.6 CustomMarqueeUnloaded This event is not used. It is for future development. N/A 5.7 Disconnected This event is fired when the connection to the DW server is closed. 5.8 Error This event is fired any time an error occurs within the control. Errors are most likely caused by issues with connectivity to the server. Avaya Professional Services Page 19

26 This event includes a MarqueeStatus parameter that can be queried to determine the cause of the error. 5.9 MessageMarqueeLoaded This event is raised when the message-specific line within the OCX is created MessageMarqueeUnloaded This event is raised when the message-specific line within the OCX is removed OAMarqueeLoaded This event is raised when the OA-specific line within the OCX is created OAMarqueeUnloaded This event is raised when the OA-specific line within the OCX is removed. Avaya Professional Services Page 20

27 5.13 Resized This event is raised anytime the marquees dimensions are changed. This is very important due to the automatic sizing of the marquees height based on its contents. You should use this event to determine when the host application should allocate more space for the marquee. Avaya Professional Services Page 21

28 6.0 Properties 6.1 DockedEdge DWMarquee.DockedEdge As ScreenEdge This property is used to determine which screen edge the marquee is configured to dock too. This property only applies if the marquee is configured for docking mode. If the marquee is configured to dock to a screen edge it is the responsibility of the host application to handle the docking behavior. Supported Values: The supported values are: ScreenEdge.BOTTOM_EDGE ScreenEdge.TOP_EDGE Access: Read-Only 6.2 Encoding DWMarquee.Encoding As EncodingTypes This property specifies the type of character encoding the marquee is configured to use. The character encoding is controlled by the EncodingType value in the registry under the key HKEY_LOCAL_MACHINE\SOFTWARE\Avaya\DSI. Supported Values: The supported values for this property are limited to: EncodingTypes.ASCII EncodingTypes.UTF8 Avaya Professional Services Page 22

29 Access: Read-Only 6.3 IsAlwaysOnTop DWMarquee.IsAlwaysOnTop As Boolean This property indicates whether the marquee is configured to be at the top of the Z-Order on the desktop. If the marquee is configured to be always-on-top, it is the responsibility of the host application to promote itself to the top of the Z-Order. Supported Values: The supported values for this property are: True False Access: Read-Only 6.4 IsDocked DWMarquee.IsDocked As Boolean This property indicates whether the marquee controls host application should dock itself to the screen edge. Supported Values: The supported values for this property are: True Avaya Professional Services Page 23

30 False Access: Read-Only 6.5 IsExitEnabled DWMarquee.IsExitEnabled As Boolean This property indicates whether the marquees host application should support allowing the agent to terminate the application. Supported Values: The supported values for this property are: True False Access: Read-Only 6.6 IsLoggingEnabled DWMarquee.IsExitEnabled As Boolean This property indicates whether logging has been enabled for the marquee. Note: Enabling logging requires a registry change on the agents PC. Supported Values: The supported values for this property are: Avaya Professional Services Page 24

31 True False Access: Read-Only 6.7 ServerIP DWMarquee.ServerIP As String This property contains the value of the ServerIP parameter used in the call to the Connect() method. Supported Values: Any string value. Access: Read-Only Note: This property can only be set through a call to the Connect() method. DWMarquee.ServerPort As Integer 6.8 ServerPort This property contains the value of the ServerPort parameter used in the call to the Connect() method. Supported Values: Any integer value. Avaya Professional Services Page 25

32 Access: Read-Only Note: This property can only be set through a call to the Connect() method. DWMarquee.Username As String 6.9 Username This property contains the value of the Username parameter used in the call to the Connect() method. Supported Values: Any string value. Access: Read-Only Note: This property can only be set through a call to the Connect() method. Note: The marquee control does not include a property for the user password due to security concerns. Avaya Professional Services Page 26

33 7.0 Enumerations & Types 7.1 EncodingTypes This enumeration is used when determining which character encoding the marquee uses for sending data to the server. Values: ET_ASCII ET_UTF8 7.2 LoggingCategory This enumeration is used when writing an entry to the log file. Values: LC_INFO LC_WARNING LC_ERROR 7.3 MarqueeStatus This enumeration covers all possible errors that may occur in the control. Values: STATUS_OK No errors STATUS_ERR_NOT_CONNECTED The marquee is not connected to the server. Avaya Professional Services Page 27

34 STATUS_ERR_MISSING_REQUIRED_DATA A required value (ex. Username) was missing from the call to Connect(). STATUS_ERR_BUSY_SENDING_DATA An attempt was made to send data out on the socket, but the socket is already sending data. STATUS_ERR_HOST_NOT_FOUND Could not find the specified DW server. STATUS_ERR_CONNECT_ABORTED The socket connection attempt was aborted. STATUS_ERR_CONNECT_REFUSED The connection attempt was forcefully refused. STATUS_ERR_NETWORK_SUBSYSTEM_FAILED A problem was encountered in the network subsystem. This could be caused by the NIC, the network driver, the Ethernet cable, STATUS_ERR_NETWORK_UNREACHABLE No connection to the network is available. This could be caused by the NIC being disabled or by the Ethernet cable being unplugged, STATUS_ERR_TIMEDOUT No response was received within the socket timeout interval. STATUS_ERR_SOCKET_SHUTDOWN An attempt was made to perform an action on the socket after the socket was already terminated. STATUS_ERR_NONRECOVERABLE A system error occurred from which the marquees network interface cannot recover. STATUS_ERR_NET_RESET A reset event was received from the network. Avaya Professional Services Page 28

35 STATUS_ERR_CONNECTION_RESET The connection with the DW server was reset. STATUS_ERR_MARQUEE_DESIGN An error was encountered while processing the group configuration information. The group configuration may be corrupt. STATUS_ERR_UNKNOWN An unknown error was encountered. 7.4 MarqueeType This enumeration is used to represent the type of marquee line. Values: CMS_MARQUEE CUSTOM_MARQUEE MESSAGE_MARQUEE OA_MARQUEE STATUS_MARQUEE 7.5 ScreenEdge This enumeration is used to represent which screen edge the marquee is configured to dock too. Values: TOP_EDGE BOTTOM_EDGE 7.6 SrollDirection This enumeration is used to represent the direction that a marquee is scrolling. Avaya Professional Services Page 29

36 Values: LEFT_TO_RIGHT RIGHT_TO_LEFT 7.7 ScrollSpeed This enumeration is used to represent the speed which a particular marquee is scrolling. Values: FAST MEDIUM SLOW STOPPED Avaya Professional Services Page 30

37 Appendix A - Troubleshooting Error Cause Solution Table 1: Appendix A - Troubleshooting Avaya Professional Services Page 31

38 Appendix B - List of Acronyms Acronym CLR CMS CMSRTC DSI DW IN MDAC OA SCM Description Common Language Runtime Call Management System CMS Real-Time Collector Desktop Statistics Integration Desktop Wallboard Instant Notification Microsoft Data Access Components Operational Analyst Service Control Manager Table 2: Appendix B - Acronyms Avaya Professional Services Page 32