Avaya Interaction Center Release 6.0 Electronic Data Unit Server Programmer s Guide

Transcription

1 Avaya Interaction Center Release 6.0 Electronic Data Unit Server Programmer s Guide DXX Issue 1.0 June 2002

2 2002, Avaya Inc. All Rights Reserved Notice Every effort was made to ensure that the information in this book was complete and accurate at the time of printing. However, information is subject to change. Preventing Toll Fraud Toll fraud is the unauthorized use of your telecommunications system by an unauthorized party (for example, a person who is not a corporate employee, agent, subcontractor, or working on your company's behalf). Be aware that there may be a risk of toll fraud associated with your system and that, if toll fraud occurs, it can result in substantial additional charges for your telecommunications services. Avaya Fraud Intervention If you suspect that you are being victimized by toll fraud and you need technical support or assistance, call Technical Service Center Toll Fraud Intervention Hotline at Providing Telecommunications Security Telecommunications security (of voice, data, and/or video communications) is the prevention of any type of intrusion to (that is, either unauthorized or malicious access to or use of your company's telecommunications equipment) by some party. Your company's telecommunications equipment includes both this Avaya product and any other voice/data/video equipment that could be accessed via this Avaya product (that is, networked equipment ). An outside party is anyone who is not a corporate employee, agent, subcontractor, or working on your company's behalf. Whereas, a malicious party is anyone (including someone who may be otherwise authorized) who accesses your telecommunications equipment with either malicious or mischievous intent. Such intrusions may be either to/through synchronous (time-multiplexed and/or circuit-based) or asynchronous (character-, message-, or packet-based) equipment or interfaces for reasons of: Utilization (of capabilities special to the accessed equipment) Theft (such as, of intellectual property, financial assets, or toll-facility access) Eavesdropping (privacy invasions to humans) Mischief (troubling, but apparently innocuous, tampering) Harm (such as harmful tampering, data loss or alteration, regardless of motive or intent) Be aware that there may be a risk of unauthorized intrusions associated with your system and/or its networked equipment. Also realize that, if such an intrusion should occur, it could result in a variety of losses to your company (including but not limited to, human/data privacy, intellectual property, material assets, financial resources, labor costs, and/or legal costs). Your Responsibility for Your Company's Telecommunications Security The final responsibility for securing both this system and its networked equipment rests with you - an Avaya customer's system administrator, your telecommunications peers, and your managers. Base the fulfillment of your responsibility on acquired knowledge and resources from a variety of sources including but not limited to: Installation documents System administration documents Security documents Hardware-/software-based security tools Shared information between you and your peers Telecommunications security experts To prevent intrusions to your telecommunications equipment, you and your peers should carefully program and configure your: Avaya-provided telecommunications systems and their interfaces Avaya-provided software applications, as well as their underlying hardware/software platforms and interfaces Any other equipment networked to your Avaya products. Avaya National Customer Care Center Avaya provides a telephone number for you to use to report problems or to ask questions about your contact center. The support telephone number is Ordering Information Avaya Publications Center Voice: International Voice: Fax: International Fax: [email protected] Write: GlobalWare Solutions Attention: Avaya Account Manager 200 Ward Hill Avenue Haverhill, MA USA Order: Document No. DXX , Issue 1.0, June 2002 To order product documentation online, go to click on Online Services, and select the appropriate product group. Warranty Avaya Inc. provides a limited warranty on this product. Refer to the Limited use Software License Agreement provided with your package. Avaya Web Page Trademarks Avaya, Conversant, CustomerQ, Definity, DefinityOne, Nabnasset, Quintus, and WebQ are registered trademarks or trademarks of Avaya Inc. in the United States or other countries or both. Portions of Avaya Interaction Center include technology used under license as listed below, and are copyright of the respective companies and/or their licensors: ActivePerl is a trademark of ActiveState Tool Corp. This product includes software developed by the Apache Software Foundation ( Cognos, Impromptu and Powerplay are registered trademarks of Cognos Incorporated. YACC++ is a registered trademark of Compiler Resources, Inc. APEX, ComponentOne, VideoSoft, True DBGrid, VSVIEW, SizerOne, VS-OCX, VSFlexGrid, VSFORUM, VSREPORTS, VSDOCX, VSSPELL, and TrueDBList are either registered trademarks or trademarks of ComponentOne LLC. CT Connect, Dialogic, Intel, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Hummingbird is a registered trademark of Hummingbird, Ltd. SearchServer is a trademark of Hummingbird, Ltd. RISC System/6000 and DirectTalk/2 are trademarks of International Business Machines Corporation in the United States or other countries or both. IBM, OS/2, AS/400, CICS, WebSphere, CT, VisualAge, and DirectTalk are registered trademarks of International Business Machines Corporation in the United States or other countries or both. Lotus and Lotus Sametime are trademarks or registered trademarks of Lotus Development Corporation and/or IBM Corporation in the United States, other countries, or both. VisualX is a registered trademark of Intergroup Technologies, Inc. ActiveX, Visio, Internet Explorer, Windows, Windows NT, Windows 2000, Win32s, SQL Server, Visual Basic, Visual C++, Outlook, and FrontPage are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. TimesTen is a registered trademark of TimesTen Performance Software. Oracle is a registered trademark, and Oracle8i and Oracle SQL/Services are trademarks or registered trademarks of Oracle Corporation. Rogue Wave and.h++ are registered trademarks of Rogue Wave Software Inc. SourcePro is a trademark of Rogue Wave Software, Inc. Siebel is a trademark of Siebel Systems, Inc. BasicScript is a registered trademark of Summit Software Company. Sun, iplanet, Java, Solaris JRE, J2EE, JavaServer Pages, and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. SPARC is a registered trademark of SPARC International, Inc. Products bearing SPARC trademarks are based on an architecture developed by Sun Microsystems, Inc. In3D is a trademark of Visual Insights, Inc. InstallShield is a registered trademark and service mark of InstallShield Software Corporation in the United States and/or other countries. ORBacus is a trademark of IONA Technologies PLC. Formula One is a licensed trademark and Tidestone Technologies, Inc. Visual Components, First Impression, and VisualSpeller are registered trademarks of Tidestone Technologies, Inc. JRun is a trademark of Macromedia, Inc. in the United States and/or other countries. Intervoice is a registered trademark of Intervoice-Brite, Inc. UNIX is a registered trademark of The Open Group in the United States and other countries. Acrobat is a registered trademark of Adobe Systems. Other product and brand names are trademarks of their respective owners. Acknowledgment This document was written by the CRM Information Development group of Avaya

3 CONTENTS BEFORE YOU BEGIN OVERVIEW OF THE EDU SERVER EDU Server Overview Interaction with the IC Repository Interaction with the DUStore Server Cooperation of EDU Servers THE ELECTRONIC DATA UNIT Definition of an EDU The EDU Lifecycle EDU Creation EDU Activity EDU Termination Listing Active EDUs The EDUID The EDU Data Table Pre-defined Data Names Value History Containers Container Names and Special Tokens Limitations of Container Syntax The Agent Container EVENT MONITORING EDU Event Monitoring Starting and Stopping Event Monitoring Setting Event Monitoring Criteria Monitoring Criteria: Syntax

4 Contents Relational Operators Boolean Operators Monitoring Criteria: Wildcards Monitoring Criteria: Examples ALARMS EDU SERVER CONFIGURATION System Considerations EDU Server Alias Name Effect of Configuration on EDU Termination Configuration Parameters The Filter dialog box CAPTURING THE EDU EVENT STREAM Capturing Events EDUDATA Server Design EDUDATA in a WAN Environment Configuration Parameters Alarms IDL SPECIFICATION EDU SERVER METHODS Exception Information Routing Requests Resurrecting EDUs EDU Method Overview THE DUSTORE SERVER Overview The DUStore Server Database DUStore Functions Electronic Data Unit Server Programmer s Guide

5 Contents EDU Behavior DUStore Server Configuration DU Store Processing DU Store Processing for Idle DU Records DUStore Server Processing as a Backup of DU Data Temporarily storing EDUIDs in the DUStore Difference between the EDUID stored in Report Server and DUStore Removing Records from the DUStore Database Tables Troubleshooting and Testing DU records and the DU Store Parameter Setting Example DUStore Server Method Overview A VDU.CREATE EXAMPLE INDEX Issue 1.0 June

6 Contents 6 Electronic Data Unit Server Programmer s Guide

7 BEFORE YOU BEGIN Typographical Conventions This guide uses the following font conventions: Font Type code italics Meaning This font signifies commands, information that you enter into the computer, or information contained in a file on your computer. This font is used to add emphasis to important words and for references to other chapter names and manual titles. It also indicates variables in a command string. jump Blue text in online documents indicates a hypertext jump to related information. To view the related material, click on the blue text. Notes, Tips, and Cautions Note: A note calls attention to important information. Tip: A tip offers additional how-to advice.! Caution: A caution points out actions that may lead to data loss or other serious problems. Contacting Technical Support If you are having trouble using Avaya software, you should: 1 Retry the action. Carefully follow the instructions in written or online documentation. 2 Check the documentation that came with your hardware for maintenance or hardware-related issues. 7

8 3 Note the sequence of events that led to the problem and the exact messages displayed. Have the Avaya documentation available. 4 If you continue to have a problem, contact Avaya Technical Support by: Logging in to the Avaya Technical Support Web site ( Calling or faxing one of the following numbers from 8:30 a.m. to 8:30 p.m. (Eastern Standard Time), Monday through Friday (excluding holidays): Toll free in the U.S. only: TECH-SPT ( ) Direct line for international and domestic calls: Direct line for faxes: Sending with your question or problem to [email protected]. You may be asked to one or more files to Technical Support for analysis of your application and its environment. Note: If you have difficulty reaching Avaya Technical Support through the above URL or address, please go to for further information. Product Documentation Readme File Most Avaya product documentation is available in both printed and online form. However, some reference material is available only online, and certain information is available only in printed form. A PDF document with detailed information about all of the documentation for the Avaya Interaction Center is included in the Doc directory on the product CD-ROM. This PDF document is also included on the separate documentation CD-ROM. The Readme file is an HTML file included on the Avaya Interaction Center software CD-ROM. This file contains important information that was collected too late for inclusion in the printed documentation. The Readme file can include installation instructions, system requirements, information on new product features and enhancements, suggested work-arounds to known problems, and other information critical to successfully installing and using your Avaya software. You may also receive a printed Addendum to the Readme, containing similar information uncovered after the manufacture of the product CD-ROM. You should review the Readme file and the Readme Addendum before you install your new Avaya software. Electronic Documentation The electronic documentation (in PDF or HTML format) for each Avaya Interaction Center product is installed automatically with the program. Electronic documentation for the entire Avaya product suite is included on the product CD-ROM and the documentation CD-ROM. You can also view the documentation set online at 8 Electronic Data Unit Server Programmer s Guide

9 Educational Services Printed Documentation You can purchase printed copies of these manuals separately. For details, see on the back of this manual s title page. License to Print the Electronic Documentation Online copies of documentation are included on the CD-ROM that accompanies every software release. An Avaya customer who has licensed software (a Licensee ) is entitled to make this online documentation available on an internal network or intranet solely for the Licensee's use for internal business purposes. Licensees are granted the right to print the documentation corresponding to the software they have purchased solely for such purposes. Right-To-Print License Terms Documents must be printed as-is from the provided online versions. Making changes to documents is not permitted. Documents may be printed only by any employee or contractor of Licensee that has been given access to the online documentation versions solely for Licensee's internal business purposes and subject to all applicable license agreements with Avaya. Both online and printed versions of the documents may not be distributed outside of Licensee enterprise or used as part of commercial time-sharing, rental, outsourcing, or service bureau use, or to train persons other than Licensee's employees and contractors for Licensee's internal business purposes, unless previously agreed to in writing by Avaya. If Licensee reproduces copies of printed documents for Licensee's internal business purposes, then these copies should be marked For internal use only within <Licensee> only. on the first page or cover (where <Licensee> is the name of Licensee). Licensee must fully and faithfully reproduce any proprietary notices contained in the documentation. The copyrights to all documentation provided by Avaya are owned by Avaya and its licensors. By printing any copy of online documentation Licensee indicates its acceptance of these terms and conditions. This license only governs terms and conditions of printing online documentation. Please reference the appropriate license agreement for terms and conditions applicable to any other use, reproduction, modification, distribution or display of Avaya software and documentation. Educational Services Avaya University provides excellent training courses on a variety of topics. For the latest course descriptions, schedules, and online registration, you can get in touch with us: Through the web at Over the telephone at (within the U.S.) (outside of the U.S.) Through at [email protected] Issue 1.0 June

10 10 Electronic Data Unit Server Programmer s Guide

11 CHAPTER 1 OVERVIEW OF THE EDU SERVER This chapter provides an overview of the EDU Server and describes its interactions with the Customer Interaction (CI) Repository and the DUStore Server. The function of the Voice Data Unit (VDU) Server and the VDUs that it creates has evolved to accommodate multiple types of media channels, and the name of the server has been changed to reflect this evolution. The server that was previously named the Voice Data Unit (VDU) Server is now called the Electronic Data Unit Server, and the data unit it creates has become the Electronic Data Unit (EDU). The server interface name has not yet been modified to reflect this change, so some of the filenames and program code still contain references to VDU. However, this manual uses the term EDU. The terms EDU and VDU are interchangeable. EDU Server Overview To successfully track a customer contact, such as a telephone call or an message, each contact must be associated with a unique detail record. That record must stay associated with the contact as it moves through the contact center system. Any system process wanting access to the contact or its associated data must explicitly reference this record. In the Avaya Interaction Center (Avaya IC), that unique detail record is the Electronic Data Unit (EDU). An EDU provides the mechanism to coordinate telecommunication, electronic communication and data processing. Each EDU identifies a specific contact. It collects both system and customer service information from the moment the contact enters the Avaya IC system until the moment it is terminated by the service agent. When the contact is terminated, the information recorded in the EDU can be archived. The EDU Server creates, stores, and manages EDUs. It creates EDUs in response to demands from Contact Engine Servers and client applications. The EDU Server manages an EDU throughout its lifecycle. It stores open EDUs, records events, and provides services that enable clients to interact with a contact. When a contact ends, the server terminates its EDU. If you are using the DUStore Server or the IC Repository, or both, all data, including contact wrap-up information, is passed to the database. 11

12 Chapter 1 Overview of the EDU Server Interaction with the IC Repository The IC Repository archives terminated EDUs for long-term storage in a relational database. The QDecision reporting package draws on this information to generate reports. Even though the entire contents of the EDU are archived in IC Repository, when an EDU has been archived it cannot be reconstructed and re-activated from the repository. You can specify the types of EDU events that are saved with the methods SetDefaultHistoryFilter() or SetHistoryFilter() methods (described in Chapter 8) and with the filter and vduhskeepname configuration parameters (described in Chapter 5). Interaction with the DUStore Server The DUStore Server maintains a database of inactive EDUs. This EDU data can be used in two ways: Reactivating EDUs EDUs can be brought back from disk to memory for reading or modifying. Recalling history Data from retired EDUs can be used to provide additional information to an agent and can be used to assist in call routing, without resurrecting them into EDU Server memory. Refer to Chapter 9 of this manual for a description of the DUStore Server. Cooperation of EDU Servers When a new EDU Server is added to Avaya IC, the existing EDU Servers must be made aware of the new server. Refer to IC Administration Volume 1: Servers & Domains for information on updating servers. When the EDU Servers have been made aware of each other, they can make requests of each other. This is most significant in the area of the Assign method. When a client assigns to an EDU Server, the Assign is relayed to other EDU Servers, and they watch for EDUs that match the client s Assign criteria as well. This makes Assign a relatively expensive operation, and clients should be designed so they only need to Assign once to specify the EDUs in which they are interested. Assigning to multiple EDU Servers is unnecessary and causes numerous problems. Every EDU identifies the server that created it and the time at which it was created. When a client requests access to an EDU, the EDU Server to which the client is assigned acts as a proxy to the EDU Server originating the EDU. 12 Electronic Data Unit Server Programmer s Guide

13 Cooperation of EDU Servers EDU Servers can also cooperate to search, in parallel, any number of DUStore Servers, making it easy to find particular EDUs no matter where they are.! Caution: When the EDU Server is shut down improperly, it is possible to lose data that has not yet been written to the DUStore. It is important, therefore, to ways follow proper shutdown procedures. Please refer to IC Administration Volume 1: Servers & Domains and IC Installation and Configuration Guide for more information. Issue 1.0 June

14 Chapter 1 Overview of the EDU Server 14 Electronic Data Unit Server Programmer s Guide

15 CHAPTER 2 THE ELECTRONIC DATA UNIT This chapter describes the Electronic Data Unit (EDU). Definition of an EDU Each telephone call, web chat, or message arriving at a contact center triggers the creation of a permanent detail record called the Electronic Data Unit (EDU). The EDU contains the information that enables Avaya IC to coordinate contact activities on the network. In addition to uniquely identifying each call, the EDU collates information about activity performed on behalf of the call and updates that information as the call traverses the service center. A typical EDU might contain the time the call arrived, transfers between agents, the time the call concluded, as well as the customer service actions performed by the agent. The EDU Lifecycle EDU Creation EDU Activity There are three stages in the lifecycle of an EDU: creation, activity, and termination. Each stage is discussed in this section. Every contact must have a corresponding EDU. Whenever an inbound call arrives at a telephone on the PBX system, a web chat or an message arrives, or a contact center agent dials out, the Telephony Server or Chat Server or Management Server invokes the VDU.Create() method. In response, the EDU Server creates an EDU and returns its unique identifier (EDUID) by invoking VDU.Create.Response() to the corresponding contact engine server. The EDU is a real-time detail record that collects strings of text from multiple sources. During its life, the dual job of the EDU is to collect information ({name, value} data couples) entered by the contact center agent or automated software, and to notify assigned clients of changes to the EDU. 15

16 Chapter 2 The Electronic Data Unit EDU Termination Each EDU has a unique identifier, its EDUID. Any application that wants to interact with an EDU, or with its associated telephone call, web chat, or message, has to request it by EDUID. Upon request, the server passes the EDUID out to other processes, thus enabling applications to ask for access to the EDU and the telephone call, web chat, or message. Through this mechanism, the data and contact logically associated with the EDU can be routed to other software processes in the service center network. Each contact is uniquely identified and that identifier stays with the contact throughout its sojourn through the system, allowing Avaya IC to coordinate contact and data processing. The EDU Server also honors requests to watch for EDUs that contain certain values. If any EDU matches the criteria, the EDU Server issues event messages (which contain the EDUID) to interested clients. (Refer to EDU Event Monitoring, on page 25.) Typically, clients want to examine EDU contents, modify EDU values, receive event notifications, transfer an EDU, or terminate an EDU. These activities are supported through method invocations. For example, a client could invoke one of the Get methods (GetOneValue(), GetSomeValues(), and so on) to ask the EDU Server to return values in an EDU. Chapter 8, EDU Server Methods, describes the methods supporting these activities. The data belonging to an EDU is modified under several circumstances, such as when clients invoke the Set methods to incorporate data into an EDU. When a contact ends, generally so does the need for an EDU. The contact center agent may need to enter wrap up information in the contact record, but afterward the EDU should be closed. The data in the terminated EDU can, optionally, be archived in the IC Repository and DUStore Server database, and the EDU is purged from the EDU Server. Before an EDU can be closed, the EDU Server must first verify that all processes are done with it. For each EDU, the EDU Server maintains an internal list of processes that have read, transferred, or modified the EDU. Any process that invokes a method using the EDUID belonging to an EDU is added to the list. When a client invokes the method VDU.Terminate(), the client's name is removed from the list. When the list is empty, the EDU can be terminated. Safeguards are built into the EDU Server to terminate suspicious EDUs, in other words, those that appear to have been lost. Any EDU that has been idle for an extended period (thirty minutes, by default) is timed-out and automatically terminated, if persistence enable is not selected. The idle time parameter can be changed with the Idle Time configuration parameter, as described in Chapter 5. Refer to Chapter 5 for a discussion of how various configuration parameters affect the timing of EDU termination. Listing Active EDUs You can view a list of active EDUs and the clients interested in them with the listvdu utility. 16 Electronic Data Unit Server Programmer s Guide

17 The EDUID The EDUID To use this utility: 1 Copy listvdu.exe from the QeSxx/bin directory to the directory in which the vesp.imp and vespidl.pk files are located, which is /etc by default. 2 Create an account in IC Manager named vesp if one does not already exist. Click the Agent tab and select the Agent New menu option. Define the name of the agent, the login Id, the group (either Admin or Default is acceptable), and the domain. Click Apply. 3 From the vesp account, enter: listvdu -iinterface -uusername -ppassword -i interface to use (often ADU or VDU, or an alias or uuid of such a server) -u user name to log in as (often Admin) -p password of user No space between -x and the text that follows. Example: listadu -ibostonadu -uadmin -pdaphnie There are defaults for all of these, but if a login error occurs, always specify -u and -p. The output contains a list of EDUs, listed by EDUID, and the interested clients for each EDU. Clients are identified by session ID, with the IP and port broken out. Resurrected EDUs are included in the list. When an EDU is created, it is automatically given an identification number (EDUID) that uniquely defines the contact. The EDUID is a 32 byte hexadecimal string partially composed of the time and date of creation of the EDU, as well as its progenitor the software process and machine that created it. The structure of an EDUID is illustrated in the following example. EDUID = 30f f Bytes Example Contents Description f42163 Timestamp. Hex representation of number of seconds since Hex representation of uniqueness value Reserved Issue 1.0 June

18 Chapter 2 The Electronic Data Unit Bytes Example Contents Description Hex representation of the IP address f43 Hex representation of a port Reserved A combination of the IP and port identifies which EDU Server is the progenitor of this EDU. The EDU Data Table EDU data consists of series of sequenced {name, value} couples that represent information about a contact. For example, the name/value pair {ani, } represents the telephone number of an incoming call. The field name ani is the name data element and is the value that is assigned to the field. Applications gain access to data by references to field names. Names are restricted to non-empty strings of less than 35 characters. Container names may contain more than 35 characters. Refer to Container Names and Special Tokens, on page 21 for information on container names. Names may contain letters (a..z, A..Z), digits (0..9), and the underscore character (_). Data element names are case sensitive. Foo, foo, and FOO refer to three different data elements. The set of field names that Avaya IC software reserves for its own system use are listed on page 19. Although they are not strictly reserved words in the technical sense, to use these field names for anything other than their pre-defined purposes could result in conflicts between applications. Values, the pieces of data that applications assign to a field, are strings that may contain from 0 to 4096 characters. Although longer strings are technically permissible, they are strongly discouraged. Any character except the null character ( \0 ) is legal. Typical EDUs contain approximately 100 values, but there is no fixed limit on size except system memory. Be advised that storing many large EDUs can adversely affect overall system performance. The EDU Server sets certain name/value data pairs, such as the EDUID. Other name/value data pairs are written into the EDU by the customer s application. Because the EDU can accept input from a variety of sources, data could come from the PBX, other servers, or the agent's application. Typical entries might include the agent's login ID, the contact s start time, and service codes. Changes to all data values are recorded, including information on who made the change and when the change was made. 18 Electronic Data Unit Server Programmer s Guide

19 Pre-defined Data Names Pre-defined Data Names The following pre-defined field names can be used in client applications, however they should be treated just like reserved words with specific meanings. Do not use these names for other than these explicit purposes! Doing otherwise could result in misinterpretation. These data names are used by the EDU Server and several other Avaya IC components. Some are read-only values to clients. Field name ani call_ref_id createtime createtime_t dnis duration endreason endtime loginid last termination modifier owner persistance persistance.delete date suspend Description Automatic Number Identification. Caller s 10-digit telephone number. The call number that the switch uses to distinguish one call from other calls, however, it is the EDUID that the EDU uses to distinguish one call from another. The date and time the EDU was created in yyyy-mm-dd hh:mm:ss format. The time_t of the EDU creation. Dialed Number Identification Service. Call recipient s telephone number or extension. The difference, in seconds, between createtime and endtime. This field is not meaningful if the EDU was stored and restored, or if the EDU was removed due to idleness. Note that this value is the length of time the EDU was in memory, not the length of the call. Set to normal for a normal termination. The time of the last Terminate method to the EDU or equivalent such as removal due to idleness. The contact center agent's Avaya IC name. The identity of the last user of the Terminate method, used as debugging information. This field identifies the login id or uuid of the user who caused the event. It is inserted into each event that is sent to reporting packages. The loginid or UUID of the application that created the EDUID or last used the Transfer/SetTransfer methods. (historical). The date and time that the EDU was last stored in the DUStore Server. The field is used to modify purging behavior of the DUStore Server. The reason that the EDU was last removed from server memory. This can be any one of the following: normal all involved parties have suspended use of the EDU. expired removed from memory due to idleness. exit server was shut down. overflow removed from memory for other EDUs. forced removed by ForceTerminate method. Issue 1.0 June

20 Chapter 2 The Electronic Data Unit Field name termination time transfercount vdu_id L_ucid iidigits lai_dnis Description A string representing the reason for the termination of the EDU: normal all users are done with the EDU and the timers that hold it in memory have expired. overflow the server has been configured to hold a maximum number of EDUs and it has been exceeded. The oldest EDU is killed to make room. expired the EDU has been idle too long and is terminated even though there are still interested parties. exit the server is being shut down. Not set. This field is inserted into each event that is set to reporting packages and is reserved for that purpose. The number of times Transfer/SetAndTransfer was used on this EDU. (historical) The unique ID of the EDU. Universal Call ID as implemented for versions 6 and beyond of the Avaya (formerly Lucent) Definity switch, CallVisor version The digits found in the originating line information field supplied by the switch. Used for the Avaya switch only. 00 Identified line, no special treatment 01 Multiparty, ANI cannot be provided 02 ANI failure 06 Hotel/Motel DN without room ID 07 Special operator handling required 20 AIOD, listed DN of PBX sent 23 Coin or Non-Coin, line status unknown Service Call 27 Coin Call 29 Prison/Inmate Service 34 Telco Operator Handled Call 52 OutWATS 60 TRS, Station Paid 61 Type 1 Cellular 62 Type 2 Cellular 63 Roamer Cellular 66 TRS, Hotel/Motel billed to room 67 TRS, Restricted line 70 Private paystation 93 Virtual Private Network call This field is supported on the legacy Definity code only. This is the phone number the call is currently routed to. The number dialed by the caller arrives as DNIS, and it is stored in the edu under primary_dnis. The number from which the caller dialed is stored under primary_ani. Both fields survive multi-site-hetero-switch transfers. They are are written once when the very first call center receives the call for the very first time, and are not updated. 20 Electronic Data Unit Server Programmer s Guide

21 Value History Value History Containers Generally, a given name in an EDU is set once and is not modified again. However, it may be useful to maintain a history of various values that a given name has had, as well as who set them and when they were set. The ability to have a single name represent a list of values and remember when they were set (and by whom) can be a significant advantage in some kinds of applications, especially those recording the state of something that varies over time. Setting the same name with new values, and relying on the EDU Server to remember previous values and timestamps, is generally much more efficient than using a container with the autoincrement token (+) (described in Container Names and Special Tokens, on page 21) to gain the same sort of effect. Note: The GetValueHistory() method fetches the previous history of a value. All the other methods (and the Assign criteria evaluations) always deal with the most recently set value for a given name. They ignore the past. The value history is maintained only in the DUStore database. It is not retained in the IC Repository. A container is a grouping of values under a common name. Containers are trees of data within an EDU. Some standard containers are maintained by Avaya IC. You can create additional containers to suit your application. Methods exist to return an entire container or subcontainer. For example, assuming use of an Agent container, you could see all the data set by the second agent to handle the contact by using the GetSubTree() method on the EDUID and asking for Agent.2. With the exception of GetSubTree() and DeleteSubTree() methods, there are no special container methods. Any method that involves getting or setting data can use container-based names. Container Names and Special Tokens You can specify container names or you can allow the EDU Server to generate container names for you based on your instructions. A number of special tokens are available for use when constructing container names. These tokens expand into appropriate strings and automate many of the steps involved in using containers. Container names have multiple parts (two or more) separated by dots. Each part, called a name token, is limited to 1 35 alphanumeric characters (underscore is also permitted), with entirely numeric name tokens reserved for use with the special tokens described below. Up to 31 dots (32 tokens total) are permitted in a container name. Note that processor usage for container names is low, but is proportional to the number of tokens in the name. Issue 1.0 June

22 Chapter 2 The Electronic Data Unit There are four special tokens available for use with container names: + The simplest special token is +. This expands into a numeric token that is greater than the last numeric token that was created with a + in that position for that container in that EDU. The first time it is used, it generates a 1. Any client that specifies a name of agent.+, is turned into agent1 by the EDU Server. The next time a client uses agent.+ in that EDU, it expands into agent.2. This makes it very easy to create subtrees within a container. The name generated in this way will never be the name of an existing subtree. (The gencount and padwidth configuration parameters, described in Configuration Parameters, on page 36, can affect subtrees created with the + token.)! The! token expands into a numeric token that belongs to the client. Tokens that belong to a given client are created via a special use of the + token. Essentially, a subcontainer created with + is assumed to belong to a caller (usually the one who created it), and the! token will find it. To create a subcontainer for another client, add the loginid of the client after the + token that creates it, as follows: agent.+jane Whatever number it creates, it is matched by a request for agent.! by client jane. If several subcontainers have been created for the same user, the! token seeks out the highest numbered (most recently created) one. If no subcontainer has been created for the client, the use of! generates an exception. To find another client s subcontainer, add the loginid of the client after the! token: containername.!loginid null The null token contains no characters. It matches the subcontainer most recently created with the + token, regardless of who it was created for or who the caller is. This is generally useful in creating and filling a subcontainer in one method call. For example, the following names given to SetValues: mydata.+ mydata..age mydata..height would create a new, numbered subcontainer in mydata, and within that same subcontainer create age and height. If mydata.+ generated mydata.3, this would generate mydata.3.age and mydata.3.height. Use of the null token should occur within the same method invocation as the use of the + token that it relates to. Otherwise, some other application might use the + token within the same container and EDU. This would change the meaning of the null token unexpectedly, unless the intent is to add data to the most recently created subcontainer no matter who created it. * The * token is permitted only within Assign methods and is described in Monitoring Criteria: Wildcards, on page Electronic Data Unit Server Programmer s Guide

23 Containers Limitations of Container Syntax The Agent Container The first token in a container name cannot be a special token. When a * token has been used, subsequent tokens in that container name must be either * or nonspecial tokens. Special tokens other than * are illegal in any request that involves multiple EDUs at the same time (for example, Assign). When a token creates a new subcontainer, subsequent tokens cannot be empty or!. No defaults or ownership has been established, so they cannot match. Note that some methods do not permit some tokens. Most do not support * and some (GetValues and methods like it) do not (meaningfully) support +. For example, in the method invocation GetValues( a.+.x ), the + token would be interpreted as create the next number in the sequence, which is not meaningful for the GetValues method. The Telephony Server creates a special container. As a contact moves between agents in a contact center, each agent may want to store information about the contact in a way that does not interfere with the next or last agent who handled the contact. To manage this, the Telephony Server creates an Agent container for each agent involved in the contact. Each agent takes a private subtree of the Agent container for the agent s own use. The first uses the name agent.1, and creates names below it agent.1.callduration, agent.1.reasoncode, and so on. The next uses the name agent.2 and sets that agent s own values in that subtree agent.2.callduration, and so on. (Refer to Telephony Server Programmer s Guide for more information on the Agent container.) The use of the Agent container allows clients to assign with agent.*, realizing a large resource savings over using multiple assigns. Issue 1.0 June

24 Chapter 2 The Electronic Data Unit 24 Electronic Data Unit Server Programmer s Guide

25 CHAPTER 3 EVENT MONITORING This chapter describes the events sent by the EDU Server. It also explains how to assign and how to establish monitoring criteria. EDU Event Monitoring The EDU Server continuously monitors the contents of EDUs for changes, and reports those changes to interested clients through event messages. Clients register their interest in EDUs by assigning themselves to the EDU Server with monitoring criteria, which is a specification describing the condition that should generate an event notice. For example, the client might request notification for every phone call originating from a specific ANI, or for every customer call handled by a particular agent. The client receives event messages about EDUs that match the specification, and continues to receive all events generated for those EDUs as long as they match the client's monitoring criteria. The EDU Server generates seven types of events that describe changes to existing EDUs. The following table lists the events and the contents of the event messages written in the EDU and sent to monitoring clients. Event Description Message VDU.auRevoir VDU.Change VDU.Delete VDU.Drop When the EDU server sends the EDUs to the DUStore, it issues "VDU.auRevoir" to the report server. A modification has occurred in a monitored EDU. Values have been deleted from the EDU. The EDU has changed and no longer matches the assign criteria. It will no longer be monitored. If the EDU later changes so that it again meets the assign criteria, the client gets a VDU.Watch event. The ID of the object being send to the DUStore. All affected {name, value} couples and the EDUID. All deleted values. The EDUID. (Sheet 1 of 2) 25

26 Chapter 3 Event Monitoring Event Description Message VDU.End The EDU has been terminated. When it terminates, the server passes a VDU.End message to all monitoring applications. All of the data elements in the EDU. VDU.Transfer The EDU has been transferred. The new client and the EDUID. VDU.Watch The EDU matches the monitoring criteria. All of the data elements in the EDU. (Sheet 2 of 2) When a client first assigns monitoring criteria to the server: All existing EDUs are checked to see if any match the specification. All subsequently created EDUs are checked for a match. Any EDUs that do match the criteria are placed under watch and a VDU.Watch event message is sent to the monitoring application. Changes to EDUs under watch are reported to the application by a VDU.Change event. Note: When a client has assigned to the EDU Server, the client should monitor the event data stream for the data in which it is interested, rather than invoking VDU.Get () methods repeatedly. As values are set in the EDU, the EDU Server sends Change events to assigned clients. The timing, order, and content of the Change events depend on the components setting the values, and is therefore variable. Starting and Stopping Event Monitoring The EDU Server methods VDU.Assign()and VDU.Monitor() let you set up monitoring conditions, and the method VDU.Deassign() lets you revoke them. Note: By default, a client does not receive change events for the EDU changes that it itself initiates to cut down on needless event traffic. It does receive other sorts of events, as well as event messages for changes caused by other clients. If the change causes a.watch or.drop event, it is reported to the client. To receive change events for the client's own changes, prefix the Assign or Monitor expression with a plus symbol (+). For example: [VDU.Assign("+*")] (The asterisk (*) in the example indicates that all EDUs in the local EDU Server should be monitored, as described in Monitoring Criteria: Syntax, on page 27.) Assigning to the EDU Server and monitoring an EDU does not add a client's name to the internal list of EDU-modifying clients. (This list of clients is described in EDU Termination, on page 16.) Assigning allows the client to watch the activity of an EDU. The client does not have to issue a VDU.Terminate() for each EDU that is being watched. 26 Electronic Data Unit Server Programmer s Guide

27 Setting Event Monitoring Criteria Setting Event Monitoring Criteria EDUs are selected for monitoring by criteria matching. A criterion (plural: criteria) is an expression that selects some EDUs and rejects others according to a defined specification. If a criteria expression is provided as a parameter to the Assign() or Monitor() method, each name/value pair in the EDU is tested against it. If the criteria determine that a match exists, the EDU is watched. Subsequent changes are sent to the client as change events. The following values cannot be successfully used in an Assign criteria: duration owner (historical) createtime termination transfercount endtime (historical) Monitoring Criteria: Syntax The general syntax of a criteria statement is: method "name relationship value" [booleanop] "name relationship value" For example: VDU.assign "loginid=joe & ani= " In the above example, the client has assigned to the EDU Server, asking it to watch for any EDU that contains these two values: Joe in the field loginid originated from (800) In other words, notify the client every time Joe gets a telephone call from Avaya Support. You can construct complex statements that evaluate multiple conditions by grouping expressions together with parentheses to control the order of evaluation. A single * character has a special meaning when used as a monitor criteria. It causes all local EDUs (those in the local EDU Server) to be watched. This is used by IC Manager and should generally be avoided by other applications, as it generates a very large amount of event traffic. Setting the monitor criteria to a null value ( ) stops monitoring. The Assign method does not accept special tokens!, +, or the null token in container names. These tokens have specific meanings for a particular EDU and vary from one EDU to another. The Assign method has no provision for names that do not have EDU-independent meaning. The Assign and Monitor methods contain criteria strings that allow you to use additional syntax. At the end of the string is a list of fields, called a projection list, enclosed in curly brackets where you can specify filter criteria. The list is comma separated with no spaces between the fields. Issue 1.0 June

28 Chapter 3 Event Monitoring For example, {specification,specification } You can specify the type of field name in three ways: 1 A simple fieldname, such as a, b, or c. 2 A wildcard container name, such as a.* or a.*.d. The wildcard designation (*) can be used after a dot (.), at either end of the specification, or followed by a dot (.) in the specification. 3 A request to retrieve all of the fields below a specified point in a container tree, as in a.b?. This format collects all of the field names below the specified point in container tree. It does not collect field names at its own level or higher on the tree. Example: +vdu_id> "" {call?,data.*,loginid} Note: Spaces are optional after the selection criteria and before the projection list. The projection list itself is optional, but no filtering is done without one. If a projection list is used, it cannot be empty. This assign criteria watches all EDUs in the system because all EDU IDs are longer than empty strings. Change events that do not reflect a change in the loginid, any matching data.*, or any subcontainer of the call container are also suppressed. Change events that not suppressed are trimmed to list only the names that are provided on the projection list. The duid, time, and modifier fields are also provided. Relational Operators Note: Watch and drop events are not modified and they are always sent with their full content. User events, which are very rare, would be modified as they are actually change events with a different name. Values can be compared to each other as described below. There are four permissible relational operators. In the description column, the term couple refers to a name/value pair. Symbol Definition Description = equal Find a couple that matches the specified name and value. Wildcards are accepted. < less than For a given name, find all couples with values less than the specified search value (string-based). > greater than For a given name, find the set of couples with values greater than the specified criteria (string-based). : exactly equal to For a given name, find a couple that exactly matches the specified value. Wildcards are not accepted. # not Expressions are not equal to each other. 28 Electronic Data Unit Server Programmer s Guide

29 Setting Event Monitoring Criteria Boolean Operators The EDU Server compares the name/value data within an EDU against the criteria string one character at a time, starting with the leftmost character, until either a mismatch occurs or one field runs out of characters. Comparisons are case-sensitive. Foo is not the same as foo or FOO. To avoid ambiguity, enclose the specified value within double quotes ( ). Within a quoted string, (\") means quote and (\\) means backslash. If the strings match character for character, they are equal. Strings can also be relatively compared. If one field runs out of characters without a mismatch, the relatively longer field is greater (for example, abc < abcd). If a mismatch occurs, the field containing the greater character is greater, (for example, 111 < 119). Because the comparison is string-based, not numeric, the field with the greater initial character is greater, (for example, 2 > 119). Wildcards are permitted only with the equal (=) operator. Boolean comparisons that return evaluations of true or false can be performed between two values. The two boolean operators are described below. Symbol Definition Description & and Both expressions must be true. or True if one or both expressions are true. For example: ani=508* dnis=3315 selects all calls from the 508 area code or directed to extension Terms may also be grouped with parenthesis for more complex expressions. Monitoring Criteria: Wildcards Instead of specifying each individual instance of a set, you can use wildcard symbols to stand in for other values. The wildcard symbols can be used in setting criteria given the following restrictions: Wildcard usage is restricted to the equal (=) relational operator. You cannot use wildcards with the less than (<), greater than (>), or exactly equal to (:) operators. Single character wildcards must have a character to match. Issue 1.0 June

30 Chapter 3 Event Monitoring Each? symbol can stand in for one character. The * symbol can either be placed at the end of a value (a so-called value trailing wildcard), or can be entered by itself to find EDUs with an instance of any value (selects all EDUs as matching). Wildcard Definition Example? Match one character pbx =??? * Find all VDUs transfercount= * Find all couples named pbx which contain a threecharacter value. Find all EDUs that have been transferred. Container names used in an Assign can use limited wildcarding. Within an Assign, an expression like agent.*.problem > selects any EDU in which any subcontainer in agent having a name of problem has nonempty text. Note that the! token is not available in an Assign, but this use of the wildcard token can be used instead. A simple way to have an EDU transferred to the attention of an agent would be for the agent to Assign using: agent.* : agentloginid then having another application setting: agent.+agentloginid to a value of agentloginid. In this way, the Assign criterion is satisfied (there exists a subcontainer in agent whose value is agentloginid, and that agent, on getting an event about the EDU, can use agent.! to refer to the subcontainer created for him). 30 Electronic Data Unit Server Programmer s Guide

31 Setting Event Monitoring Criteria Monitoring Criteria: Examples The following examples demonstrate how to instruct the server to monitor EDUs that fulfill specific criteria. The last three examples all identify the same set of EDUs those from area code (203). As you can see, there is flexibility in specifying monitoring criteria. Choose the method that best fits the current circumstances. Criteria Example Description ani = " " (ani > " ") & (ani < " ") ani = "203*" ani = "203???????" Identify any EDU containing the value " " in the field ani. Monitor all calls from the 203 area code. Monitor all calls from the 203 area code. (This is the most efficient way to do this.) Monitor all calls from the 203 area code. Issue 1.0 June

32 Chapter 3 Event Monitoring 32 Electronic Data Unit Server Programmer s Guide

33 CHAPTER 4 ALARMS The IC Manager application provides system administration tools for monitoring alarm events. Visual and sometimes auditory alarms (beeps) are triggered whenever the system detects problems that require human intervention, such as server failures. Alarms are categorized as Emergency, High, Low, or Informational. (For more information about monitoring alarms, refer to IC Administration Volume 1: Servers & Domains.) To minimize Alarm Server traffic, alarms that occur repeatedly are gathered by the EDU Server and raised periodically. The repeat count indicates how many times the condition has occurred since the alarm was last raised. The following is a description of the alarms specifically associated with the EDU Server. Alarm Name Priority Description Cause/Recommended Action AssignFail Emergency Cannot Assign to EDU %s; ignoring it BadVDUInDS Emergency Bad UUID %s in DS s list of EDU servers DumpVDU High EDU overflow, killing eldest Another EDU Server across the WAN is unavailable. A site has been cut off. WAN features may not be available. Corruption in the DS has made it impossible to identify other EDU Servers for WAN work. Contact customer support ( ). The EDU limit set by the vdus parameter has been reached. The oldest EDUs are being removed to make room for newer ones, which may disrupt contact handling. This alarm is generated for each EDU that is retired. If this alarm is generated, the EDU Server is not configured properly. Increment the value of the vdus parameter. Determine if EDUs are being left in the server when they are no longer needed, and possibly adjust timer settings (nouserinterval, idletime). Refer to Chapter 5 for a discussion of EDU termination rules. (Sheet 1 of 2) 33

34 Chapter 4 Alarms Alarm Name Priority Description Cause/Recommended Action FailVDUCon High Connection to <uuid> closed; n dropped watchers [reason] LostVDUEvents High n events lost due to network congestion or error NoEventSink High Cannot find the server named in the eventsink configuration parameter. A Vesp_Request call failed to send a request to the specified server NoMeInDS Emergency This EDU Server is not listed in the DS for this EDU Server s domain. NoVDUOS Emergency Cannot request of DUStore, %lx (losing EDUs) VDUbad High EDU %s corrupt, and cannot be resurrected Victims High Shutdown with %u EDU%s in existence; %s. Saving to VDUOS or Objects discarded A connection to a remote server has failed. The UUID of the remote server is reported, as is the number of clients that were assigned to the server. The reason is often VDU.ServerFailed. Event handling requests are timing out. n represents the approximate number of events that have been lost. The server could not be reached. History is being lost. If you are not using a data repository, set the database configuration parameter to 0 and restart the EDU Server. Check the vesp.imp and vespidl.pk installation files. If they do not list the eventsink server and interface, reinstall the files and restart the EDU Server. The configuration of servers and domains is incorrect. Contact customer support ( ). The DUStore Server could not be reached. EDUs are not being archived. If you do not have a DUStore Server installed, set parameter DUStore to 0 and restart the EDU Server. An EDU was requested but could not be restored due to database damage. The EDU Server has been shut down with EDUs still active. If the DUStore service is available, the server attempts to save the EDUs there. This may take considerable time and delays server shutdown. If the DUStore is not configured, the EDUs are simply lost. (Sheet 2 of 2) 34 Electronic Data Unit Server Programmer s Guide

35 CHAPTER 5 EDU SERVER CONFIGURATION This chapter contains configuration information for the EDU Server. System Considerations The Max Active Vdus configuration parameter should be set with consideration for system capability. The number of contacts that can be effectively handled by the EDU Server is proportional to the system's available memory and processor speed. A typical EDU (in other words,, a typical contact) requires 10K in memory. Complex contact flows might require 30K or more. Memory can be conserved by using the same data names in many EDUs. The memory space for name storage is shared. The memory used for storage of values, however, is not affected. Processor usage may be decreased by setting values in groups as opposed to one at a time. When possible, gather sets of name/value pairs and apply them all at the same time. EDU Server Alias Name When setting an alias name for the EDU Server, note that the name local EDU is reserved. In a WAN environment, it is used to segregate an EDU Server when it has been taken off-line. Refer to IC Administration Volume 1: Servers & Domains for information about setting alias names for servers. Effect of Configuration on EDU Termination Several configuration parameter settings interact to determine when EDUs are terminated. The server periodically scans for EDUs that need to be cleaned out. This has the effect of batching DUStore Server operations to some degree. This interval is controlled with scaninterval, which can be dropped to 1 second if less batching is desirable. The scan causes cleaned out EDUs to be sent to the DUStore Server. No more than maxkills EDUs are sent to the DUStore Server per scan. By changing scaninterval and maxkills, you can control how much work the EDU sends to the DUStore Server, and how quickly. The value of maxkills could be set to 256 at a busy site, and possibly higher for high values of scaninterval. 35

36 Chapter 5 EDU Server Configuration If maxkills is too low, EDUs build up in memory, having no users and waiting to be shipped out to the DUStore Server on a subsequent scan. Eventually, the EDUs limit is reached, and you begin receiving Dump VDU alarms, because the oldest EDUs are terminated to make room for each new EDU created. An EDU with no interested users is given nouserinterval seconds, plus a random number of seconds between 0 and randomkillinterval (120), to exist. When that time expires, it is picked up on the next scan. The worst case for an EDU without users is: remain active for scaninterval+nouserinterval+randomkillinterval. Expected is: scaninterval/2 + nouserinterval + randomkillinterval/2. The random time addition avoids a situation where an application fails to terminate a number of EDUs, then stops. All of the EDUs that were opened by the application become candidates for cleanup at the same time. By adding some randomness to the cleanup-time, these are spread over several scans, causing any individual scan to do less work. Configuration Parameters The EDU Server is configured through the IC Manager. For detailed configuration instructions, refer to IC Administration Volume 1: Servers & Domains. The following table lists the label used when configuring with IC Manager, followed in parentheses by the parameter name as it is required internally by the server. Note: For configuration parameters specific to the EDUDATA service, refer to Chapter 6. For configuration parameters specific to the DUStore Server, refer to Chapter 9. Label Checkpoint frequency (checkpoint.interval) Idle Time (idletime) No User Interval (nouserinterval) Description Minimum interval period in seconds between requests to checkpoint a specified EDU into the DUStore server. A value of 1 means do not checkpoint. Number of minutes an EDU may remain inactive before being terminated. The default is 90 minutes. Minimum is 1 minute, default is 30 minutes, maximum is 15 hours. Minimum number of seconds an EDU may linger in memory when there are no users active for it. Default is 60 seconds. Minimum is 1 second, default is 15 seconds, maximum is 90 minutes. (Sheet 1 of 4) 36 Electronic Data Unit Server Programmer s Guide

37 Configuration Parameters Label Random Kill Interval (randomkillinterval) Description Maximum number of seconds an EDU stays in memory after the usual timers have expired. The default is 30, the range is 1 to 180 seconds. Random intervals are useful when a large number of EDUs are simultaneously suspended or deleted, causing the DUStore to be flooded with requests. Handling the requests over a two-minute period decreases server stress. Where such a situation is unlikely, more predictable timing and better memory usage result from a setting of 1. While testing to see if EDUs are being retired when they should be, 1 is also an appropriate setting. Scan Interval (scaninterval) Max Active Edus (vdus) Watchers (watchers) Enable Reporting Interface (database) Pool Size (poolsize) Pool Growth Increments (poolgrowsize) Initial Number of fields (initialdatalength) Pool Re-Pack (%) (repackfree) Enable persistance (dustore) Number of seconds to wait between checking various EDU Server timers. Higher values may save some CPU time. Lower values provide behavior that is more predictable during prototyping and testing. Default is 4 seconds. Minimum is 1 second, maximum is 60 seconds. Assume that other timers in the EDU could be off by as much as (this interval + 1) to start. The maximum number of EDUs that the EDU Server will keep active at the same time. If Enable persistence is selected, it will send an alarm and the Oldest EDU will be stored in DUStore. This value should be somewhat greater than the number of agents using this server to handle calls. The default varies by release. Always set this value explicitly. The number of EDUs that can be effectively handled by the EDU Server is proportional to the system s available memory and processor speed. A typical EDU requires 40K in memory. Active agent sessions might require 60K or more. The number of clients who are interested in assigning to EDU Servers. To start, this should be equal to the number of agents in the contact center (across all contact centers in a WAN environment), plus a few extra. Default varies by release. Always set this value explicitly, as the default is very large and some memory is wasted in each EDU if the value is set too high. If set too low, Assigns are rejected. Should be checked if you want to enable the use of HISTADD reporting, unchecked if not. The default is checked. The initial amount of memory allocated for data belonging to each EDU. Increase the pool size if a large amount of data is stored and performance needs to be improved. The default is The amount of memory to add to the string pool for each EDU if the pool runs out. Increase the pool size allocation when more memory is needed to store strings or events. The default is The number of fields expected in an EDU. This does not limit the number of fields, but when this number is exceeded, the server must reallocate space. The default is 128. If using containers, this value should possibly be increased to 256 or 512. When the specified percentage of the pool belonging to an EDU becomes free, the EDU Server repacks the pool to save memory. Sites at which performance is critical and memory is plentiful may consider using a value of 100. The default is 25. Enables the use of the DUStore Server. Check the checkbox to enable or uncheck to disable. (Sheet 2 of 4) Issue 1.0 June

38 Chapter 5 EDU Server Configuration Label DuStore EDU Batch Size (maxkills) Poll Wait (pollwait) Maximum number of Revisions (maxkeptrevisions) Number of Cached Edu events (keepevents) Retry Interval (serverretryinterval) Reset Interval (serverresetinterval) Data Element Names Description The maximum number of EDUs that are sent to the DUStore Server in one set. The minimum is 1 and the default is 60. Sets the interval for the Toolkit's select() method, in hundredths of a second. The default value is 50 (50 milliseconds). Low values increase CPU utilization. High values (over 100) may affect the accuracy of the scaninterval parameter. Determines the number of revisions of a value that are kept for access with the GetValuesHistory() method. The default is 4, which is generally recommended. Determines the number of events to be kept in memory for each EDU. The default is 256. A setting of 64 is recommended as a reasonable number of events to be kept in memory. High values may increase Eventsink throughput, low values may conserve memory. Specifies the number of seconds to wait between automatic attempts to reassign to servers. The minimum is 6 seconds, maximum is 48 hours, default is 1 minute. Setting this value below 30 seconds in a production environment is not recommended, as it does a synchronous DS call for a list of EDU Servers and attempts an asynchronous Assign to any of them it isn't already assigned to. If the Assign fails (the request function itself fails), the offending EDU Server is removed from the list and not retried automatically. The retry is only attempted if the Assign callback reveals an error or a ServerFailed event arrives. Specifies the number of seconds to wait between attempts to reassign to servers after receiving a VDU.FailVDUCon alarm. The minimum is 0, maximum is 48 hours, default is 2 seconds. Names of data elements in EDU events to be sent to the server specified with the Event Sink option. Each element must be entered on a separate line with the Edit dialog. If this option is not set, all data elements are stored. The EDUID field is always stored. Use of wildcards is permitted. Use this parameter with care. Filtering elements from the End event may adversely affect reporting capability. Suspend Interval (suspendinterval) Edu Data Percent (vdudata.percent) Database Search on Create (findcreatestoresearch) Duindex Lookup1 (duindex.lookup1) Duindex Lookup2 (duindex.lookup2) Number of seconds before an EDU, which is suspended by use of the Suspend method by all users, is considered for Suspension. This parameter can be overridden by a higher value in the Suspend method. The minimum is 1, maximum is 20 minutes, default is 1 second. The percentage of EDUs that are sent to the VDU data feed, used for random sampling. The minimum is 0, maximum is 100, default is 0. Enables a WAN wide DUStore search on the FindOrCreate method. Check the checkbox to enable or uncheck to disable. The name of one of the fields used to index the EDU in the DUStore Server. Used with the Find method. The name of one of the fields used to index the EDU in the DUStore Server. Used with the Find method. (Sheet 3 of 4) 38 Electronic Data Unit Server Programmer s Guide

39 Configuration Parameters Label Duindex Info1 (duindex.info1) Duindex Info2 (duindex.info2) Duindex Info3 (duindex.info3) Edudata Alarm Priority (vdudata.alarm.priority) Edudata Event Name (vdudata.eventname) Edudata Event Ifname (vdudata.event.ifname) Edudata Data Only Name (vdudata.data.onlyname) Description The name of one of the fields used to identify the EDU in the DUStore Server. Used with the Find method. The name of one of the fields used to identify the EDU in the DUStore Server. Used with the Find method. The name of one of the fields used to identify the EDU in the DUStore Server. Used with the Find method. An alarm priority used when raising an alarm related to the VDUDATA feed. Values are low, high, and emergency. The names of events that may be sent to the VDUDATA feed. If there are no events identified, all events are sent. Use this parameter multiple times to specify multiple events. Sends an event to the VDUDATA feed only if the event contains this field. This parameter can be specified multiple times to allow multiple valid names. Filters events to the VDUDATA feed so they only contain this field. The parameter can be specified multiple times to allow multiple valid names. (Sheet 4 of 4) Issue 1.0 June

40 Chapter 5 EDU Server Configuration The following configuration parameters are not presented on the EDU tab in IC Manager. They can be set on the Config tab of the EDU Server Editor dialog. Name filter (filter) Description Sets the filter for determining which EDU events are sent to the server specified with the Eventsink configuration parameter. The event types are start, change, delete, transfer, user, and data. A plus sign (+) marks the event type for storage, a minus sign ( ) excludes the event type from storage. End events cannot be filtered out. The data parameter encompasses all event types. -data is the default. Each filter criterion must be entered on a separate line, with subsequent lines taking precedence. Examples: data +change only change and end events are stored +change data only end events are stored Note that drop and watch events are sent to clients but are not included with the +data filter. vduhskeepname (reportkeepname) Names of data elements in EDU events to be sent to the server specified with the Eventsink configuration parameter. This parameter is ignored if the Eventsink server is HISTMAP (the Report Server.) Each element must be entered on a separate line. If this parameter is not used, all data elements are sent. (The VDUID field is always stored.) Use of wildcards is permitted. Use this parameter with care. Filtering elements from the End event may adversely affect reporting capability. Name gencount padwidth Description Specifies the number of instances of a subcontainer created with the + token that can exist at one time. If more than this number are created the earliest is deleted. For example, to limit the number of subcontainers of the ts container, you could set gencount to ts.3. When ts.+ creates ts.4, ts.1 is deleted. When ts.5 is created, ts.2 is deleted, and so on. The default is 0, which specifies no limit (all generations of a subcontainer are kept). The gencount value should be set to accommodate the maximum number of active contacts for each media channel. Specifies the number of digit positions required in a container name token. Numbers are padded with zeroes to this position. For example, to specify the number of digit positions for the second token of the ts container, you could set padwidth to ts.4. Subcontainers would then be named ts.0001, ts.0002, and so on. The default is 0, which specifies no padding. 40 Electronic Data Unit Server Programmer s Guide

41 Configuration Parameters The Filter dialog box The Filter dialog box in IC Manager allows you to set the filter for determining which EDU events are sent to the server. The Event Filter option (described in the previous section) performs the same function but differs in that the Event Filter setting does not take effect until the server is restarted, and then is persistent. The Filter dialog box settings take effect immediately but are lost when the server is restarted. The server must be running when this tab is used. Enter the event types to be filtered from the database. The possible values are '+charge', '+start' and '-data' which are used to turn on change and start events. The default value "-data" turns everything possible off. Note: Previous versions of Avaya IC included the VDU History Server, which has been replaced by the Report Server. To support existing installations during a transitional period, events can be sent to both servers. 1 Use the default for the eventsink parameter (HISTMAP.EventsIn) to send events to the Reporting server. 2 Set the Reporting server s eventforward parameter to VDUHS.EventsIn. The Reporting server forwards all EDU events to the VDUHS. The vduhs parameter, used in previous versions of the EDU Server to enable access to a database server, should no longer be used. Issue 1.0 June

42 Chapter 5 EDU Server Configuration 42 Electronic Data Unit Server Programmer s Guide

43 CHAPTER 6 CAPTURING THE EDU EVENT STREAM This chapter describes use of an EDUDATA Server to capture the EDU event stream. This server was formerly named the VDUDATA Server and still executes the file vdudata.c Capturing Events The EDU Server allows access to the EDU event stream without use of the IC Repository. This is accomplished through use of an EDUDATA Server. Avaya IC provides skeleton code for an EDUDATA Server (vdudata.c), which can be used as a basis for a customer-designed EDUDATA Server. This file, and a sample executable, are distributed with Avaya IC. An EDUDATA Server replaces use of the IC Repository. If an EDUDATA Server is used, it is expected that the database configuration parameter in the EDU Server would be turned off (set to 0). Having both the IC Repository and EDUDATA Servers handling event streams may cause performance issues, and customers would be responsible for monitoring and tuning the system to handle the additional event traffic. Events are sent to the EDUDATA Server on the same schedule as they would be sent to the IC Repository: every scaninterval seconds, new events are sent to interested servers. In addition, the termination of an EDU causes all unsent events to be sent at that point, regardless of the scaninterval. On a busy system, the stream of method invocations is more or less continuous. Resurrected EDUs (described in Chapter 9) never send events to an EDUDATA Server. EDUDATA Server Design The EDUDATA Server is responsible for accepting an EDUID and a sequence of events in each invocation of its EventData method. It must immediately deal with this data and return a VESP_SUCCESS value. The EDUDATA Server should be designed to use the data and return as quickly as possible. Experience shows that writing the sequence of events to a simple ASCII data file is reasonably quick, but attempting SQL Insert operations with a database engine is too time consuming, and causes congestion in Telephony as the requests begin to back up. Install the EDUDATA Server with the name EDUDATA and no alias. 43

44 Chapter 6 Capturing the EDU Event Stream EDUDATA in a WAN Environment In WAN environments, only locally held EDUs send events to the EDUDATA Server. Each WAN EDU service would presumably communicate with its own EDUDATA Server. Configuration Parameters To use an EDUDATA Server, set the following configuration parameters in the EDU Server. Following the table is a sample configuration illustrating use of these parameters. Parameter Setting Description vdudata.percent vdudata.eventname A value between 1 and 100 event name (for example, VDU.new or VDU.end) 100 causes all events of all EDUs (except resurrected EDUs) to be sent to the EDUDATA Server. Values from 1 to 99 represent a percentage of EDUs that are selected randomly at creation to send their events to the EDUDATA Server. This provides simple support for random sampling. If this parameter is not set, the EDUDATA Server is not enabled. Specifies a specific event to be sent to the EDUDATA Server. If an EDU is elected to send its events to the EDUDATA Server and this parameter has been set, only events with the specified name are sent. There may be multiple instances of this parameter. vdudata.event.ifname data name Specifies a specific data name. If an event is elected to be sent to the EDUDATA Server, but the event does not contain any data names specified in any vdudata.event.ifname variable, the event will not be sent. There may be multiple instances of this parameter. (Sheet 1 of 2) 44 Electronic Data Unit Server Programmer s Guide

45 Configuration Parameters Parameter Setting Description vdudata.data.onlyname data name Specifies a specific data name to be included when the event is sent to the EDUDATA service. Any name not specified is not included in the event. (This variable differs from the vduhskeepname parameter in that even the vdu_id can be removed from the event.) vdudata.alarm.priority <>, low, high, or emergency Specifying this variable with a null value causes two EDUDATA alarms to be shut off VDU.NoVDUDATA and VDU.ErrVDUDATA. Specifying low, high, or emergency changes the priority of these alarms to the specified value. database 0 This parameter should be set to 0 when using an evdudata Server. (Sheet 2 of 2) The following represents a sample configuration for using an EDUDATA Server: vdudata.percent 100 vdudata.event.name VDU.end Send events from all EDUs... but only their end events... vdudata.event.ifname critical vdudata.event.ifname hostile and only if that event contains a data name of "critical" or "hostile" vdudata.data.onlyname account vdudata.data.onlyname dnis vdudata.data.onlyname ani and strip out all data but the account, dnis and ani fields. Another example configuration: vdudata.vdupercent 33 vdudata.event.name VDU.end Send events from approximately one third of all EDUs but only their end events, in their entirety. Issue 1.0 June

46 Chapter 6 Capturing the EDU Event Stream Alarms The following alarms are generated by the EDU Server in response to EDUDATA problems. Alarm Priority Text Description VDU.NoVDUDATA high Cannot request of VDUDATA, [errorcode], [vduid] This alarm is generated for each attempt to use an EDUDATA Server if that service is not defined in the Directory Server. Display and priority of this alarm can be changed with the vdudata.alarm.priority configuration parameter. VDU.ErrVDUDATA high Failed request in VDUDATA, [errorcode], [vduid] This alarm is generated if the EDUDATA Server is found, but returns an ORBStatus other than success. Display and priority of this alarm can be changed with the vdudata.alarm.priority configuration parameter. VDU.SlowVDUDATA high VDUDATA has 65 requests outstanding This alarm is raised if the EDU Server has more than 64 requests to the EDUDATA Server outstanding (unanswered). The alarm will not be raised again unless the number of outstanding requests has dropped below eight and again risen over Electronic Data Unit Server Programmer s Guide

47 CHAPTER 7 IDL SPECIFICATION The Interface Definition Language (IDL) is defined within CORBA standards. It is used to create interfaces that are called by client objects and provided by object implementations. The following is the IDL description of the EDU Server. interface genericdu virtual { ORBStatus Create( in SeqCouple values, out stringvduid ); ORBStatus Terminate( in stringvduid ); void TerminateMine(); ONEWAY EventsIn(in string vdu_id, in SeqEvent events); ORBStatus FindByKey( in string name, in string value, out stringvduid ); ORBStatus Find( in string search_criteria, in unsigned long, scope, out SeqString matches ); ORBStatus FindExtended( in string search_criteria, in unsigned long scope, out SeqCouple matches ); ORBStatus GetOneValue( in string vduid, in string name, out string value ); ORBStatus GetValues( in string vduid, out SeqCouple c ); ORBStatus GetActive( out SeqString vduseq ); ORBStatus SetOneValue( on string vduid, in string name, in string value ); ORBStatus SetValues( instring vduid, in SeqCouple values ); ORBStatus DeleteValue( in string vduid, in string pattern ); ORBStatus IncrValue( in string vduid, in string name, in long incr, out string newvalue ); ORBStatus Assign( in stringmonitorcriteria ); ORBStatus Monitor( in stringmonitorcriteria ); ORBStatus Transfer( in string vduid, in string to ); ORBStatus SetAndTransfer(in string vduid, in string to, in SeqCouple values ); ORBStatus GetValuesHistory( in string vduid, in unsigned long flags, out SeqLong headers, out SeqString names, out SeqSeqSeqString values ); ORBStatus GetValueHistory( in string vduid, in string name, out SeqString values, out SeqString when, out SeqString who ); ORBStatus GetSubTree( in string vduid, in string name, out SeqCouple matches ); ORBStatus GetSomeValues( in string vdu_id, in string name, out SeqCouple matches ); ORBStatus SetValuesExtended( in string vdu_id, in SeqCouple data, out SeqString newnames ); 47

48 Chapter 7 IDL Specification ORBStatus DeleteValues( in string vdu_id, in SeqString names ); ORBStatus DeleteOneValue( in string vdu_id, in string name ); ORBStatus DeleteSubTree( in string vdu_id, in string name ); ORBStatus SetAndTerminate( in string vdu_id, in SeqCouple data ); void GetUserSessions( in string vdu_id, out SeqString users ); //Server ONLY ORBStatus RemoteWatcher( in unsigned long handles, in string cri ); ORBStatus ForwardEvent( in unsigned long handles, in Event Event ); } void SetDefaultHistoryFilter( in unsigned long mask ); ORBStatus SetHistoryFilter( in unsigned long mask ); interface ADU : genericdu, General { const unsigned long NO_OS = 0x00; const unsigned long ASK_OS = 0x01; const unsigned long NET_NO_OS = 0x02; const unsigned long NET_ASK_OS = 0x03; }; 48 Electronic Data Unit Server Programmer s Guide

49 CHAPTER 8 EDU SERVER METHODS This chapter defines the methods provided with the EDU Server. Clients request Contact Engine Servers to perform various functions by issuing server-specific method invocations. These methods behave in a similar fashion across all servers. For example, when you invoke any of the various EDU Server Set methods, existing values are overwritten. Values that did not previously exist are created. With the exception of the Delete methods, all of the EDU Server methods generate change events to indicate changes or additions. If an error occurs, exceptions are raised. Note: In some program examples the line length was longer than could fit across the page. Keep in mind that an actual program line cannot be arbitrarily split. Exception Information The EDU Server methods may return the following exception information: Cannot use empty token Improper special token for this method Improper use of a special token No listing for home server for that VDU No such name: <name> No such VDU: <vduid> No WAN VDU services in this version Not a VDU id: <vduid> Server only attribute Too many characters in token Too many dot separators Too many names at once Unknown error VDU is read-only You are not a server Cannot find subcontainer for that owner First token must be normal here No match (or illegal usage) Cannot access invalidated member 49

50 Chapter 8 EDU Server Methods Routing Requests In an environment with several EDU Servers, any method that accepts an EDUID routes the request to another EDU Server if the EDU named is not local to the first server. EDUIDs contain location data, so a server can identify which system owns each EDU. Resurrecting EDUs Unless otherwise noted, all methods that accept an EDUID resurrect the EDU if it has been retired to the DUStore. Refer to The DUStore Server, on page 75 for more information about resurrecting EDUs. EDU Method Overview The following is a brief description of the methods available for use with the EDU Server. VDU.Assign VDU.Create VDU.CreateExtended VDU.Deassign VDU.DeleteOneValue VDU.DeleteSubTree VDU.DeleteValues VDU.EventsIn VDU.Find VDU.FindByKey VDU.FindExtended VDU.ForceTerminate VDU.ForwardEvent VDU.GetActive VDU.GetOneValue VDU.GetSomeValues Create a session with the EDU Server. Create a new EDU. Create a new EDU and return the time that the EDU was created. Destroy a session with an EDU Server. This is equivalent to DeleteValues with a single name. DeleteOneValue on the given name and every name in the subcontainer beneath it, cutting a branch from the tree a container represents. Given a list of names, this method removes from the EDU the name and its value history, in effect making the EDU smaller. Adds a user-defined EDU event to an EDU. Returns a list of EDUIDs that match a simple criterion. Finds one active local EDU based on a single search criterion. Identical to the Find method, but for each EDU found, it returns an EDUID and values that are indexed by the Object Store. Forces the EDU object to be deleted from memory and from the database both, so it can no longer be used. Reserved. Finds all the active EDUs at the time the call is made. Retrieves one value from an EDU. Returns all names and values matching a container name. (Sheet 1 of 2) 50 Electronic Data Unit Server Programmer s Guide

51 VDU.Assign VDU.GetSubTree VDU.GetUserSessions VDU.GetValues VDU.GetValueHistory VDU.GetValuesHistory VDU.IncrValue VDU.Monitor VDU.RemoteWatcher VDU.SetAndTerminate VDU.SetAndTransfer VDU.SetDefaultHistoryFilter VDU.SetHistoryFilter VDU.SetOneValue VDU.SetValues VDU.SetValuesExtended VDU.Terminate VDU.TerminateMine VDU.Touch VDU.Transfer Returns all names and values in the subcontainer named by name. Returns the sessions of all clients believed to have an interest in the EDU. Retrieves all of the values of an EDU. Returns everything that is known about the named field's values in an EDU. Returns everything that is known about all values in an EDU. A useful alternative to using SetOneValue and GetOneValue to modify a value when there is a risk that two applications might conflict. Changes Assign criteria. Reserved. Combines a SetValues and a Terminate. Combines SetValues and Transfer into a single call, as these operations often occur together. (historical) Reserved. Allows the caller to specify which types of events are saved when an individual EDU is sent to the IC Repository, overriding the default history filter for one EDU. Sets one EDU data element. Sets one or more EDU data elements. Performs a SetValues, but in addition returns a parallel list of names that it created while resolving container names. Removes the client's name from the list of interested parties for one EDU. Removes the client's name from the list of interested parties for all EDUs. Touches an EDU when it is called.. Historical. (Sheet 2 of 2) VDU.Assign IDL Syntax ORBStatus Assign( in string monitorcriteria ) ; Description Create a session with the EDU Server. When a session is created, events are sent to the Avaya IC client. Issue 1.0 June

52 Chapter 8 EDU Server Methods The Assign() method ignores resurrected EDUs (ones brought back from the Object Store database). When multiple EDU Servers are in use, Assigns watch all calls in the domain of the EDU Servers and notify the client with events when they occur. This makes Assign a relatively expensive operation. Clients should be designed so they only need to Assign once to specify the EDUs in which they are interested. Assigning to multiple EDU Servers is unnecessary and causes numerous problems. (Refer to Cooperation of EDU Servers, on page 12, for additional information.) Input Parameters monitorcriteria Information used to select EDUs for monitoring, consisting of name and value strings. If values contain anything other than letters and numbers (for example, spaces), they should be enclosed in double quotes, and \ or " characters must be quoted by a \ character. Refer to Event Monitoring, on page 25 for more information. Returns VESP_SUCCESS VESP_ERROR Request was successful Request was unsuccessful C Program Example status = Vesp_Assign_Request( "VDU.Assign", callback, user_data, event_callback, session, "login=user" ); VDU.Create IDL Syntax ORBStatus Create( in SeqCouple values, out VDU_ID vduid ) ; Description This method creates a new EDU. This function is usually performed by the Telephony Server and is hidden from normal application development. The Telephony Server sets the creation timestamp and other information about the call. Refer to Appendix A for a programming example of an asynchronous create. Input Parameters values Initial values of the EDU, not to exceed 1023 values. Output Parameters vduid Electronic Data Unit Identifier. 52 Electronic Data Unit Server Programmer s Guide

53 VDU.CreateExtended Returns VESP_SUCCESS VESP_ERROR Request was successful Internal error in EDU Server C Program Example _IDL_SEQUENCE_Couple *seq_couple; VDU_ID vduid; /* receives the id of the created VDU */ /* Create space for values */ seq_couple = vesp_couple_seq_create(); /* fill in the field for the new VDU entry */ vesp_couple_seq_add_couple_values( seq_couple, "name1", "value1" ); vesp_couple_seq_add_couple_values( seq_couple, "name2", "value2" ); vesp_couple_seq_add_couple_values( seq_couple, "name3", "value3" ); /* Create the new VDU */ status = Vesp_Request( "VDU.Create", callback, 0x2132, session, seq_couple, &vduid ); vesp_couple_seq_delete( seq_couple ); VDU.CreateExtended IDL Syntax ORBStatus CreateExtended( in SeqCouple values, out VDU_ID vduid, out string timet) ; Description This method creates a new EDU and returns the time that the EDU was created. This function is usually performed by the Telephony Server and is hidden from normal application development. The Telephony Server sets the creation timestamp and other information about the call. Input Parameters values Initial values of the EDU, not to exceed 1023 values. Output Parameters vduid timet Electronic Data Unit Identifier. The time that the EDU was created. Returns VESP_SUCCESS VESP_ERROR Request was successful Internal error in EDU Server Issue 1.0 June

54 Chapter 8 EDU Server Methods VDU.Deassign IDL Syntax ORBStatus Deassign( ) ; Description Returns Destroy a session with an EDU Server. When a session is deassigned, the flow of events from the EDU Server to the client ceases. Events may continue to arrive until the response for this method is received. It is not an error to deassign when no session exists. VESP_SUCCESS Request was successful VDU.DeleteOneValue IDL Syntax ORBStatus DeleteOneValue( in VDU_ID vduid, in string name) ; Description This is equivalent to DeleteValues with a single name. If used with a container name ( a.b ), you only delete that one name, a.b. However, the EDU Server methods is not able to address names below that point. Although a.b.c may still exist, the EDU Server cannot find it, even though GetSubTree on a still sees them. Resolving a.b.c depends on resolving a.b, which does not exist anymore. Callers should generally not delete elements from non-leaf positions. Input Parameters vduid name Electronic Data Unit Identifier. Name whose values are to be deleted from the EDU. VDU.DeleteSubTree IDL Syntax ORBStatus DeleteSubTree( in VDU_ID vduid, in string name) ; Description This method does a DeleteOneValue on the given name and every name in the subcontainer beneath it, cutting a branch from the tree a container represents. If given a simple container name ( data ) it deletes the entire container. Input Parameters vduid name Electronic Data Unit Identifier. Name whose values are to be deleted from the EDU. VDU.DeleteValues IDL Syntax ORBStatus DeleteValues( in VDU_ID vduid, in SeqString names) ; 54 Electronic Data Unit Server Programmer s Guide

55 VDU.EventsIn Description Given a list of names, this method removes from the EDU the name and its value history, in effect making the EDU smaller. Values are deleted from active memory only. This method does not interact with the database. If used with a container name ( a.b ), you only delete that one name, a.b. However, the EDU Server is not able to address names below that point. Although a.b.c may still exist, the EDU Server cannot find it, even though GetSubTree on a still sees them. Resolving a.b.c depends on resolving a.b, which does not exist anymore. Callers should generally not delete elements from non-leaf positions. Input Parameters vduid names Electronic Data Unit Identifier. List of names whose values are to be deleted from the EDU. VDU.EventsIn IDL Syntax Description Input Parameters ONEWAY EventsIn(in string vdu_id, in SeqEvent events); This function adds an EDU event to an EDU. Values in the EDU are updated to reflect the names and values in the event. vduid event Electronic Data Unit Identifier. The event information. Each event must include an event name to describe the event. Requests without an event name are rejected. Returns No return value. One-way requests do not have any returns. C Program Example Event *event; /* Create space for record */ event = vesp_event_create( "Update" ); vesp_event_add_couple( event, "name1", "value1" ); /* Create the new VDU History event entry */ status = Vesp_Request( "VDU.EventsIn", callback, 0x2132, session, vduid, event ); /* release memory we allocated */ vesp_event_delete( event ); VDU.Find IDL Syntax ORBStatus Find( in string search_criteria, in unsigned long scope, out SeqString matches ) ; Issue 1.0 June

56 Chapter 8 EDU Server Methods Description This method returns a list of EDUIDs that match a simple criterion. The EDUs found may be active, or stored in the Object Store, or in other WAN EDU Servers or Stores, depending on the setting in scope. EDUs found in the Object Store are not resurrected. If the search is to include Object Stores (VDU_ASK_OS, VDU_NET_ASK_OS ), the criterion is limited to an expression of the form: name = value & name = value in which the names are limited to indexed fields (defined by the index configuration parameter). If the search does not include Object Stores, the criteria can be any expression an Assign method would accept. The Find method, especially one distributed across the WAN, can take time, as it cannot reply until it receives a response from all the other servers it contacts and combines the lists it receives. A WAN-wide search proceeds in parallel across all involved EDU Servers, but the speed is still limited to the speed of the slowest single search. In the worst case, the request may start other servers that had not been started yet, which can entail a significant delay. Input Parameters search_criteria scope Criteria to be used for the search, consisting of name and value strings. If values contain anything other than letters and numbers (for example, spaces), they should be enclosed in double quotes, and \ or " characters must be quoted by a \ character. Scope can be: VDU_NO_OS Check the local EDU Server only. VDU_ASK_OS Check the local EDU Server and local Object Store only. VDU_NET_NO_OS Check the WAN EDU Servers but no Object Stores. VDU_NET_ASK_OS Check WAN EDU Servers and their Object Stores. Output Parameters matches List of VDUIDs meeting the search criteria. Note that an empty list is considered valid and returns VESP_SUCCESS. Returns VESP_SUCCESS Request was successful VDU.FindByKey IDL Syntax ORBStatus FindByKey( in string name, in string value, out VDU_ID vduid ) ; 56 Electronic Data Unit Server Programmer s Guide

57 VDU.FindExtended Description This method finds one active local EDU based on a single search criterion, or key. Each EDU contains at least one unique element, typically the unique call ID supplied by the PBX/ACD. VDU.FindByKey() is used by the Telephony Server. FindByKey() searches only the local EDU Server for active EDUs. It does not resurrect EDUs from the Object Store database. Input Parameters name value Search key to find EDU. Value to match if name is found. Output Parameters vduid Electronic Data Unit Identifier. Returns VESP_SUCCESS Request was successful C Program Example Locate a VDU having a key containing status = Vesp_Request( "VDU.FindByKey", callback, 0x2132, session, "key", "1137", &vduid ); VDU.FindExtended IDL Syntax Description ORBStatus FindExtended( in string search_criteria, in unsigned long scope, out SeqSeqCouple matches ); The FindExtended() method is identical to the Find method, but for each EDU found, it returns a sequence of couples, the first element of which is the EDUID, and subsequent elements are values that are indexed by the DUStore. If the only purpose of finding a set of EDUs is to discover the values of fields that happen to be indexed by the Object Store, this method yields the needed values without the cost of resurrecting the EDUs that match. Issue 1.0 June

58 Chapter 8 EDU Server Methods Input Parameters search_criteria scope Criteria to be used for the search, consisting of name and value strings. If values contain anything other than letters and numbers (for example, spaces), they should be enclosed in double quotes, and \ or " characters must be quoted by a \ character. Scope of the search: VDU_NO_OS Check the local EDU Server only. VDU_ASK_OS Check the local EDU Server and local Object Store only. VDU_NET_NO_OS Check the WAN EDU Servers but no Object Stores. VDU_NET_ASK_OS Check WAN EDU Servers and their Object Stores. Output Parameters matches List of EDUIDs meeting the search criteria and values indexed by the Object Store. Note that an empty list is considered valid and returns VESP_SUCCESS. Returns VESP_SUCCESS Request was successful VDU.FindOrCreate IDL Syntax Description ORBStatus FindOrCreate( in SeqCouple match, in SeqCouple oncreate, out string vdu_id) ; This method searches the local server for an EDU that exactly matches all names and values in the match. It does not support wildcards. If a match is not found on the local server, it searches other EDU servers. If a match is found, it returns the id of the EDU. If multiple matches are found, the id of the most recently created EDU is returned. If no match is found, the local server creates the EDU with the names and values from the combined list of match and oncreate. The id is then returned. Note: This method is intended to by used by the Avaya Toolkit. If you know the EDU needs to be created, it is recommended that you use the VDU.Create method because it is faster and much more efficient. 58 Electronic Data Unit Server Programmer s Guide

59 VDU.ForceTerminate Input Parameters name value Search key to find EDU. Value to match if name is found. Output Parameters vduid Electronic Data Unit Identifier. Returns VESP_SUCCESS VESP_ERROR Request was successful. Requires values to find EDU. The match parameter may be empty. VDU.ForceTerminate IDL Syntax Description ORBStatus EDU.ForceTerminate(in string duid) Forces the EDU object to be deleted from memory and from the database both, so it can no longer be used. VDU.ForwardEvent IDL Syntax ORBStatus ForwardEvent( in unsigned long handleis, in Event Event) ; Description This method is reserved. It is the method by which EDU Servers pass events to each other. Client applications should not call this method. VDU.GetActive IDL Syntax ORBStatus GetActive( out SeqVDU_ID vduseq ) ; Description This method finds all the active EDUs at the time the call is made. Note that only EDUs currently in memory, not those stored to disk by the DUStore, are found. Output Parameters vduseq A list of active EDUs. Returns VESP_SUCCESS Request was successful C Program Example Issue 1.0 June

60 Chapter 8 EDU Server Methods SeqVDU_IDvdu_ids; /* Initialize a sequence of VDUs (0 specifies no limit) */ vdu_ids._maximum = 0; vdu_ids._length = 0; vdu_ids._buffer = NULL; status = Vesp_Request("VDU.GetActive", callback, user_data, session, &vdu_ids ); VDU.GetOneValue IDL Syntax ORBStatus GetOneValue( in VDU_ID vduid, in string name, out string value ) ; Description This method retrieves one value from an EDU. Input Parameters vduid name Electronic Data Unit Identifier. EDU element to be returned. Output Parameters value One returned value from the EDU. Returns VESP_SUCCESS VESP_ERROR Request was successful EDUID or name not found C Program Example Get the value of "myfavoriteelement" from the EDU named by vduid. char *value; status = Vesp_Request( "VDU.GetOneValue", callback, 0x2132, session, vduid, "myfavoriteelement", &value ); VDU.GetSomeValues IDL Syntax Description ORBStatus GetSomeValues( in VDU_ID vduid, in string name, out SeqCouple matches) ; This function returns all names and values matching a container name. It is one of the few that accepts the * token. Thus, a name of data.*.emergency returns names such as data.1.emergency, data.scott.emergency, and so on. 60 Electronic Data Unit Server Programmer s Guide

61 VDU.GetSubTree Input Parameters vduid name Electronic Data Unit Identifier. A name. By intent, a container name. Output Parameters matches All names and values in that subcontainer. VDU.GetSubTree IDL Syntax ORBStatus GetSubTree( in VDU_ID vduid, in string name, out SeqCouple matches) ; Description This function returns all names and values in the subcontainer named by name. It can be given a container name (agent) or a subcontainer name (agent.2) and returns all names and values from that point down. Input Parameters vduid name Electronic Data Unit Identifier. A name. By intent, a container or subcontainer name. Output Parameters matches All names and values in that subcontainer. VDU.GetUserSessions IDL Syntax ORBStatus GetUserSessions( in string vduid, out SeqString users) ; Description This method returns the sessions (as strings) of all clients believed to have an interest in the EDU. If empty, the EDU is being held in memory by a grace timer, such as nouserinterval. Input Parameters vduid Electronic Data Unit Identifier. Output Parameters users Sessions of interested clients. Issue 1.0 June

62 Chapter 8 EDU Server Methods Returns VESP_SUCCESS Request was successful VDU.GetValues IDL Syntax ORBStatus GetValues( in VDU_ID vduid, out SeqCouple values ) ; Description This method retrieves all of the values of an EDU. Input Parameters vduid Electronic Data Unit Identifier. Output Parameters values A sequence to contain EDU information. Returns VESP_SUCCESS VESP_ERROR Request was successful EDUID was not found C Program Example Get all of the data elements active in a specific EDU. _IDL_SEQUENCE_Couple *values; /* init an empty, unlimited sequence of Couples */ seq_couple = vesp_couple_seq_create(); status = Vesp_Request( "VDU.GetValues", callback, 0x2132, session, vduid, seq_couple); VDU.GetValueHistory IDL Syntax Description ORBStatus GetValueHistory( in string vduid, in string name, out SeqString values, out SeqString when, out SeqString who) ; GetValueHistory returns everything that is known about the named field's values in an EDU. It reports on all the values the field has had (up to the limit specified with the maxkeptrevisions configuration parameter), who set them, and when. The returned arrays are parallel, with the bottommost element being the most recent. 62 Electronic Data Unit Server Programmer s Guide

63 VDU.GetValuesHistory Input Parameters vduid name An EDUID of an existing EDU. The name of a field. Output Parameters values when who A list of values to which the named field has been set. When the field was set to each value, time_t string. The login ID (consistent with EDU.GetValuesHistory) of the client that set each value. Returns VESP_SUCCESS VESP_ERROR Request was successful EDUID was not found VDU.GetValuesHistory IDL Syntax Description ORBStatus GetValuesHistory( in VDU_ID vduid, in unsigned long flags, out SeqLong headers, out SeqString names, out SeqSeqSeqString values) ; GetValuesHistory returns everything that is known about all values in an EDU. For each named field in an EDU, it reports on all the values the field has had (up to the limit specified with the maxkeptrevisions configuration parameter), who set them, and when. By providing the various VDU_GSGET flags, you can control which of these values are returned. The output in headers is a list of your specified flags, one per long integer. This indicates the order in which the bottommost sequence of strings in the values parameter are filled. Thus, if you specify (VDU_GSGETVALUE VDU_GSGETTIME), headers would come back with two long integers, one containing VDU_GSGETVALUE and one containing VDU_GSGETTIME. The bottommost sequences in the values parameter would list values in the same order. The output in names is a list of all the data names within the EDU. Container elements each get their own entry. The topmost sequences in values are in the name order, so if names[3] is x, values[3] is the sequence that describes the history of x. Values itself runs three deep. The topmost level is parallel to the names sequence. The next level down represents one entry for each value that names has had over time. If a value has only been set once (a common case) this sequence only has one element. The lowest level runs parallel to the headers parameter, and has one element for each of the kinds of data requested (any combination of text, time, and who). Issue 1.0 June

64 Chapter 8 EDU Server Methods For example, field quark was set twice, once at EDU creation (11:37:00am, by Scott, to truth ) and again at call transfer (11:38:00, by Jane, to charm ). Specifying flags = VDU_GSGETTIME VDU_GSGETVALUE VDU_GSGETWHO would yield: header[0] = VDU_GSGETVALUE; header[1] = VDU_GSGETTIME; header[2] = VDU_GSGETWHO; //first subelement is the text //second is time //third is who names[?] = quark ; //one of the names returned will be quark values[?][0][0] = truth ; values[?][0][1] = ; values[?][0][2] = Scott ; values[?][1][0] = charm ; values[?][1][1] = ; values[?][1][2] = Jane ; //values[13] is parallel to names[13], and the //first value that was set was truth //the time_t it was set (11:37:00am) //Scott set it //next value set was charm //set at this time //by this loginid Input Parameters vduid flags An EDUID of an existing EDU. One or more of the VDU_GSGET flags, OR'd together. Flags are: #define VDU_GSGETVALUE 0x01 #define VDU_GSGETTIME 0x02 #define VDU_GSGETWHO 0x04 Output Parameters headers names values A list of VDU_GSGET values. A list of EDU data names. A list of data values (one per name), which are lists of value histories (one per value), which are lists of fields (text, when, and who). Returns VESP_SUCCESS VESP_ERROR Request was successful EDUID was not found 64 Electronic Data Unit Server Programmer s Guide

65 VDU.IncrValue VDU.IncrValue IDL Syntax Description ORBStatus IncrValue( in VDU_ID vduid, in string name, in long incr, out string newvalue ) ; This method is a useful alternative to using SetOneValue and GetOneValue to modify a value when there is a risk that two applications might conflict. This method changes one EDU data element. Any element that does not exist is created. An element that exists is overwritten if permission allows. The value of the element is treated as a number, and converted to a long integer (by use of the C atol function). The specified increment is added, and the element s value is set to the result. Elements that do not exist are treated as if they contained a zero (0). The increment may be a negative value. The atol function is robust in that if it cannot recognize a number, it returns zero. The method stores the resulting, incremented value as a decimal digit string without extraneous spaces or leading zeros. Thus, incrementing x2 by one results in 1 and incrementing 00034E6 by one results in 35. Input Parameters vduid name incr Electronic Data Unit Identifier. The name of the EDU element to change or create. Increment value. Output Parameters newvalue The new value of the element, after the increment. Returns VESP_SUCCESS VESP_ERROR Request was successful EDU not found, or the element cannot be changed C Program Example char *result; status = Vesp_Request( "VDU.IncrValue", callback, 0x2132, session, vduid, "some_numeric_element", 1L, &result ); VDU.Monitor IDL Syntax ORBStatus Monitor( in string monitorcriteria ) ; Description This method changes Assign criteria. It works like Assign in all respects. You must have previously assigned (and have not since deassigned) to use this method. Issue 1.0 June

66 Chapter 8 EDU Server Methods Input Parameters monitorcriteria Monitor criteria, consisting of name and value strings. If values contain anything other than letters and numbers (for example, spaces), they should be enclosed in double quotes, and \ or " characters must be quoted by a \ character. Refer to Chapter 3, Event Monitoring for additional information. Returns VESP_SUCCESS VESP_ERROR Request was successful Invalid monitor criteria VDU.RemoteWatcher IDL Syntax ORBStatus RemoteWatcher( in unsigned long handleis, in string cri) ; Description This method is reserved. Client applications should not call this method. When multiple EDU Servers are listed in one directory, any Assign, Monitor, or Deassign method invocation is communicated by the local EDU Server to all other EDU Servers by a RemoteWatcher method invocation. RemoteWatcher events are included in the EDU Server log file following Assign, Monitor, or Deassign events. They take the form: uuid.remotewatcher( nnnn, "abcde" ) where: uuid is the UUID of the EDU Server nnnn is a number used internally abcde is a string identifying the Assign or Monitor criteria. A blank string indicates a Deassign method invocation VDU.SetAndTerminate IDL Syntax ORBStatus SetAndTerminate( in VDU_ID vduid, in SeqCouple data ) ; Description This method combines a SetValues and a Terminate, and is recommended for efficient call wrapup. Input Parameters vduid data Electronic Data Unit Identifier. Values to be set, not to exceed 1023 values. 66 Electronic Data Unit Server Programmer s Guide

67 VDU.SetAndTransfer VDU.SetAndTransfer IDL Syntax ORBStatus SetAndTransfer( in VDU_ID vduid, in string to, in SeqCouple values ) ; Description This historical method combines SetValues and Transfer into a single call, as these operations often occur together. If the operation succeeds, it generates a Transfer event containing all changes made to the VDU. This operation is usually performed by Telephony components, not client software. Input Parameters vduid to Electronic Data Unit Identifier. A string representing the receiving client. values A list of names and values to apply to the EDU, not to exceed Returns VESP_SUCCESS VESP_ERROR Request was successful EDU not found, set failed, or client not a valid string C Program Example /*Transfer a VDU. */ char *to; _IDL_SEQUENCE_Couple *values; /* init an empty, unlimited sequence of Couples */ seq_couple = vesp_couple_seq_create(); /* fill in the field for the new VDU entry */ vesp_couple_seq_add_couple_values( seq_couple,"loginid", "meritha" ); to = ORB_object_to_string( VESP_ORB, &environment, to_object); status = Vesp_Request( "VDU.SetAndTransfer", callback, 0UL, session, vduid, to, seq_couple ); vesp_couple_seq_delete( seq_couple ); VDU.SetDefaultHistoryFilter IDL Syntax void SetDefaultHistoryFilter( in unsigned long mask ) ; Description This method is reserved. Client applications should not call this method. Issue 1.0 June

68 Chapter 8 EDU Server Methods This method allows the caller to specify which types of events are saved when EDUs are sent to the IC Repository (or other database specified with the eventsink configuration parameter). The filter takes effect in subsequently created EDUs, not existing ones. All events generated for all subsequent EDUs are checked against the permissions in the bits set in the mask argument. Events already generated are not affected. The SetHistoryFilter() method can be used to override the default filter for individual EDUs. The bits are defined in the file "vespidl.idl" as: HS_NOSTART HS_NOCHANGE HS_NOTRANSFER HS_NOUSER HS_NODELETE (unsigned short)0x01 Do not record new events (unsigned short)0x02 Do not record change events (unsigned short)0x04 Do not record transfer events (unsigned short)0x08 Do not record user-defined events (unsigned short)0x10 Do not record delete events End events (VDU.End) cannot be filtered out. They must be included in the stored EDUs. VDU.SetHistoryFilter IDL Syntax ORBStatus SetHistoryFilter( in VDU_ID vduid, in unsigned long mask ) ; Description This method allows the caller to specify which types of events are saved when an individual EDU is sent to the IC Repository (or other database specified with the eventsink configuration parameter), overriding the default history filter for one EDU. The filter takes effect immediately. All subsequent events generated are checked against the permissions in the bits set in the mask argument. Events already generated are not affected. The bits are defined in the file vespidl.idl as: HS_NOSTART HS_NOCHANGE HS_NOTRANSFER HS_NOUSER HS_NODELETE (unsigned short)0x01 Do not record new events (unsigned short)0x02 Do not record change events (unsigned short)0x04 Do not record transfer events (unsigned short)0x08 Do not record user-defined events (unsigned short)0x10 Do not record delete events The end event (VDU.End) cannot be filtered out. It must be included in the stored EDU. Input Parameters vduid mask Voice Data Unit Identifier. Permission bits to be set. 68 Electronic Data Unit Server Programmer s Guide

69 VDU.SetOneValue Returns VESP_SUCCESS Request was successful C Program Example Vesp_Request_Sync( "VDU.SetHistoryFilter", /* method identification */ &ev, /* environment pointer */ session, /* session object */ &request, /* pntr to pntr to request structure */ vduid, /* a vdu id */ HS_NOUSER /* check ev for errors as needed */ Vesp_Request_Delete(session, request); /* The permission bit to be set for this VDU */ ); VDU.SetOneValue IDL Syntax Description ORBStatus SetOneValue( in VDU_ID vduid, in string name, in string value ) ; This method sets one EDU data element. An element that does not exist is created. An element that exists is overwritten if permission allows. The following fields are restricted and cannot be changed by applications: vduid transfercount createtime endtime owner termination duration update_time Setting values can generate watch, change, and drop events. Input Parameters vduid name value Electronic Data Unit Identifier. The name of the EDU element to change or create. The value to be set. Returns VESP_SUCCESS VESP_ERROR Request was successful EDU not found, or the element cannot be changed Issue 1.0 June

70 Chapter 8 EDU Server Methods C Program Example /*Set one value. */ status = Vesp_Request( "VDU.SetOneValue", callback, 0x2132, session, vduid, "my_favorite_element", "new value" ); VDU.SetValues IDL Syntax ORBStatus SetValues( in VDU_ID vduid, in SeqCouple values ); Description This method sets one or more EDU data elements. Data elements that do not exist are created. Existing elements are updated if permission allows. The following fields are restricted and cannot be changed by applications: vduid transfercount createtime endtime owner termination duration update_time Setting values can generate watch, change, and drop events. Input Parameters vduid values Electronic Data Unit Identifier. A sequence containing EDU information, not to exceed 1023 values. Returns VESP_SUCCESS VESP_ERROR Request was successful EDU not found or values not able to be set C Program Example /* Example of an initialized sequence with fixed values: */ status = Vesp_Request( "VDU.SetValues", callback, 0x2132, session, vduid, &values ); VDU.SetValuesExtended IDL Syntax Description ORBStatus SetValuesExtended( in VDU_ID vduid, in SeqCouple data, out SeqString newnames) ; This function performs a SetValues, but in addition returns a parallel list of names that it created while resolving container names. For example, if the data SeqCouple contained two names, agent.!.x and data.+, the newnames list might be returned containing agent.2.x and data Electronic Data Unit Server Programmer s Guide

71 VDU.Terminate This method is useful for applications that need to know how names were generated, especially for applications that make repeated use of the + token and need to be able to go back and fill in values in the various subcontainers they have created. The following fields are restricted and cannot be changed by applications: vduid transfercount createtime endtime owner termination duration update_time Setting values can generate watch, change, and drop events. Input Parameters vduid Electronic Data Unit Identifier. data Values to be set, not to exceed Output Parameters newnames List of names created to resolve container names. VDU.Terminate IDL Syntax ORBStatus Terminate( in VDU_ID vduid ) ; Description This method indicates that the application is finished with the EDU and no longer needs to access it. This gives it permission to be deleted entirely from the servers, which includes DUStore but not IC Repository. If an application is done with an EDU for the moment but expects to need it again later, it should call the Suspend method instead of Terminate. EDUs are not deleted until all applications have called a Terminate method against them or if the EDU remains unused in the DUStore Server for a specified number of days. Input Parameters vduid Electronic Data Unit Identifier. Returns VESP_SUCCESS VESP_PARTIAL_ SUCCESS VESP_ERROR Request was successful, the EDU is gone The EDU was not found in memory. Specified EDU does not exist Issue 1.0 June

72 Chapter 8 EDU Server Methods C Program Example status = Vesp_Request( "VDU.Terminate", callback, 0x2132, session, vduid ); VDU.TerminateMine IDL Syntax void TerminateMine( ) ; Description When an EDU is created, read, modified, or transferred, the client's name is added to an internal list of clients. When this method is invoked, the client's name is removed from the list for all EDUs. When each EDU's list is empty, the EDU is purged and, optionally, sent to the IC Repository. The Terminate() method is marginally faster than TerminateMine(), and is therefore preferable when the EDUID is known. It is important to realize that transferring a call does not automatically end a client s responsibility toward the EDU. The client must use the VDU.Terminate() or the VDU.TerminateMine() method to signal that it has no further interest in each EDU. Returns There is no return value. C Program Example status = Vesp_Request( "VDU.TerminateMine,"callback, 0x2132, session) ; VDU.Touch IDL Syntax ORBStatus Touch( in string vduid ) ; Description This method touches an EDU when it is called to prevent it from being harvested from memory out of idleness. It adds the caller to the list of interested parties for the EDU. If the caller is already on the list, this method does nothing. Input Parameters vduid Electronic Data Unit Identifier. Returns VESP_SUCCESS VESP_ERROR Request was successful EDU not found in memory or in the DUStore Server VDU.Transfer IDL Syntax ORBStatus Transfer( in VDU_ID vduid, in string to ) ; 72 Electronic Data Unit Server Programmer s Guide

73 VDU.Transfer Description This historical method transfers an EDU. A successful transfer changes the value of the transfercount element and generates an EDU.Transfer.event to any process watching the VDU. This operation is usually performed by Avaya IC components, not client software. Transferring an EDU does not end the client s responsibility to the EDU. When the client has finished processing the EDU, the client must use VDU.Terminate() to signal that it has no further interest in modifying the EDU. Input Parameters vduid to Electronic Data Unit Identifier. A string representing a new client. Returns VESP_SUCCESS VESP_ERROR Request was successful EDU not found, or client not a valid string C Program Example /* Transfer a VDU */ char *to; to = ORB_object_to_string(VESP_ORB, &environment, object); Vesp_Request( "VDU.Transfer", callback, 0UL, session, vduid, to); Issue 1.0 June

74 Chapter 8 EDU Server Methods 74 Electronic Data Unit Server Programmer s Guide

75 CHAPTER 9 THE DUSTORE SERVER Overview As Avaya IC has evolved to provide connectivity to multiple media channels such as voice, , and the internet, the need to manage the resulting objects that may remain in memory for a longer period becomes more significant to the contact center. Improving the recovery of ADU and EDU data during system faults is also important because customer interactions, previously measured in seconds and minutes for telephone calls, may now be measured in hours or even weeks for s and web chats. The DUStore Server has been developed to replace the VDUOS Server to address these issues. The DUStore Server interfaces to a database of inactive EDUs. It stores EDUs in the database in their entirety. When an EDU Server method is invoked for an EDU that is no longer in memory, the DUStore Server restores the EDU as if it were assigned to an active contact. This ability is transparent to the client application. The DUStore Server also enables you to delete expired EDUs from the database. The DUStore Server Database The DUStore Server interfaces to a DCO-enveloped database to take advantage of database independent features in DCO. The database must be previously installed and fully functioning on the system. The data stored by the DUStore Server is encoded by the EDU Server and cannot typically be decoded by any other client or server, including the DUStore Server. EDU records are accessed by key fields, which are specified with the EDU Server s index configuration parameter. A maximum of three key fields, in addition to the EDUID key field, can be specified. An additional two non-key fields may also be specified. The following defines the schema for the DUStore database table. 75

76 Chapter 9 The DUStore Server DUStore database table Field Name Index Type Width Description vdu_id Yes char 32 The EDUID of the object from EDU Server. This field is unique for all records in the database. deletedatetime Yes char 32 The date and time, at or after, when the object should be deleted. data No Var-length char NA EDU data information in proprietary format. datalength Yes char 32 The number of bytes in the Data field. lookup1 Yes char 32 Indexed field that can be associated with the EDUID. lookup2 Yes char 32 Indexed field that can be associated with the EDUID. info1 No Var-length char NA Additional information that can be associated with the EDUID. info2 No Var-length char NA Additional information that can be associated with the EDUID. DUStore Functions EDU Behavior The DUStore server works along with DU (ADU or EDU) servers. The server provides two main functions. Allowing idle DU records to remain active in the system for extended periods without adding to the overhead of the associated DU server. Providing a backup server to store DU records in the case the DU server is shut down, either normally for maintenance or abnormally due to an abnormal shutdown. The other functions of the DUStore Server are: Deleting EDUs when they are ended. Purging EDUs that have been forgotten. In the DUStore Server model, an EDU is either Active or Deleted. If an EDU is Active, it may be Cached in the EDU Server s memory or Persisted in the DUstore database. An Active EDU can therefore be in one of the following states: Active:Cached Active:Persisted 76 Electronic Data Unit Server Programmer s Guide

77 DUStore Server Configuration Deleted The EDU Server treats EDUs in either of these Active states the same with the possible exception of some timing implications. When an EDU is created, it is in the Active:Cached state. It remains that way until one of the following has occurred: It has been left idle for a configured period, usually under 3 hours. It needs to be removed from the cache to make room for another EDU. All users who have read or written the EDU have done a Terminate or Suspend method on the DUID. The server is shut down. If the EDU is brought from the DUStore Server to the EDU Server, it remains cached until these same conditions occur. The EDU Server can put copies of the EDUs into the DUStore Server without changing the status of the EDU to Active:Persisted for backup purposes in the event of an EDU Server failure. This is called checkpointing and it is a configurable parameter for the EDU Server. Refer to Configuration Parameters, on page 36 for more information. DUStore Server Configuration Each EDU Server is associated with a DUStore Server through the domain setting in IC Manager. For information on assigning servers to domains, refer to IC Administration Volume 1: Servers & Domains. Refer to Configuration Parameters, on page 36 for a complete description of the EDU Server configuration parameters. In addition, DUStore Server supports the parameters listed in the following table. Refer to IC Administration Volume 1: Servers & Domains for information on setting these configuration parameters. Issue 1.0 June

78 Chapter 9 The DUStore Server The following parameters are presented on the DUStore Server tab of the DUStore Server configuration: Label Default delete deletion age (Days) Deleted per scan Scan Interval (min) Local adl Purge Alarm Description The number of days that the EDU is held, in the absence of other information, before it is deleted from the system. The default is 60 days. The number of EDUs that are deleted at a time each time the system is scanned for EDUs that have expired, until all expired EDUs have been deleted. Default iis The period, in minutes, that the server looks for EDUs that have expired. The default is 15. Note that if a large number of EDUs have expired during the scan interval, all expired EDUs will be deleted during the scan. Indicates if the.adl the system is using is installed on the local machine instead of the one that resides on the database. Default is unchecked for no. This setting raises an alarm if a delete scan finds any EDUs that meet the criteria for deletion. Default is checked for yes. The following configuration parameters are presented and set on the Database tab for the DUStore Server. Name Application Database Login ID Database Password Connection Log Size Log Level Log File Description The name of the application. The default is qrepository. User name with permission to write to the database. This is the DS login id, not the database login id. Password for the user specified above. If you edit the server, the database password is affected and must be changed to save the new configuration. In the Server Editor, delete the existing password and click Ok. Then, reopen the Server Editor, re-enter the password and click Apply or Ok. The name of the database connection to be used to associate the server with the database. The default is QConnections. The maximum size for the log file. The default is 2.5 MB. The level of information to be printed to the log. The default is 3. The location and file name in which errors are logged. If no entry is made, errors are logged in dustore.log in your standard log directory. 78 Electronic Data Unit Server Programmer s Guide

79 DUStore Server Configuration DU Store Processing The DUStore server works along with DU (ADU or EDU) servers. The server provides two main functions. A way for idle DU records to remain active in the system for extended periods without adding to the overhead of the associated DU server. A backup server to store DU records in the case the DU server is shut down, either normally for maintenance or abnormally due to an abnormal shutdown. DU Store Processing for Idle DU Records Every interaction that is tracked by the IC system has an associated EDU record. Agents and queues have associated ADU records. Client components work with the DU records by issuing requests to the EDU or ADU server. Each client must terminate its interest in DU records that are read or updated. The DU server maintains a record of all clients that have used particular DU records. The DU stays active until all clients have terminated interest. The DU servers have a configuration parameter idle time. This parameter is the approximate number of minutes that a DU record will be maintained by the DU server without any client requests. If a DU record has been active in the DU server and has not been requested or updated for the length of time greater than the idle time, the DU server will then remove the DU record from its control. If a DU Store server is being used, the record is then processed by the DU Store and written to the DU Store database. If a client makes a subsequent request for the DU record that is no longer in memory, the DU Server will request the record from the DU Store. The DU Store then retrieves the record from the database and provides the DU record to the DU server. The DU server then completes the request. EDU Server idle time should be tuned based on the your needs. Because overhead is required to use the DU Store, the idle time should be longer than the maximum amount of time that a voice or chat interaction will be in the system without active EDU server activity. interactions often are in queue for significant periods of time. For example, the center may operate Monday through Friday, but can arrive anytime. could then be in queue for several days. It is unusual for Chat or Voice interactions to be in queue or in process with the agent for more than 30 minutes. For this reason, the DU Store server often acts as part of the normal process for , but as an exception process for Voice and Chat. You may want to use the DU Store as part of standard processing for voice or chat when using special processing such as virtual hold applications. As a general rule, idle time should be set at a value that will be long enough to keep the EDU in active status on the EDU server for all interactions where a customer or agent is actively involved. Allow the EDU to be stored in the DU Store when the customer or agent is not working actively with the interaction. Issue 1.0 June

80 Chapter 9 The DUStore Server DUStore Server Processing as a Backup of DU Data You can use DU Data to store critical information. When the DU record is normally ended (all interested parties have terminated interest), the critical data contained in the DU record is written by the Report Server into the interaction repository database. When the EDU server sends the EDUs to the DUStore, it issues "VDU.auRevoir" to the report server. If the DU server is shut down with active DU records, the data associated with the DU will be lost unless the DU Store backs up the data. The DU server has two important configuration variables related to backup functionality. Enable Persistence. If checked, the DUStore server will be used for backup functions. If not checked, no backup functionality will be provided. In many situations, the system will perform with full integrity with persistence turned off. This is the case where data stored in the DU record is not used for back end reporting. A possible candidate for turning persistence off is in the configuration of the ADU server or a Voice or Chat only EDU server. Checkpoint frequency. The default value is -1, which means that no checkpointing will occur. If the -1 value is used, the DUStore server will not be used unless the DU server is shutdown normally. During the shutdown process, all active DU records are written to the DUStore server, providing the backup functionality. Checkpoint frequency should be set if the data contained in the active DU records are critical enough to merit the checkpoint overhead. If enabled, at an DU server scan interval, all active DU records that have not beenwritten to the DU Store within the checkpoint frequency will be updated. Note that this not a guarantee that changes will not be recorded for the given length of time. It is a guarantee that a rapid series of changes will not cause a rapid series of updates to the database. Changes are gathered up so that that database is not, typically, hit more often than Interval seconds apart. When checkpointing is on, the goal is to record DU data in the database as soon as possible, because the reason for checkpointing is to aid in recovery if the system crashes. The checkpoint interval merely prevents rapid changes from accessing the database faster than it can respond. In the case of the alarm at server shutdown, the server only writes to the DUStore what data it needs to, to insure the DU is intact. When the system is recovered, a client requesting the specific DU record will cause the DU to be restored from the DUStore. If no client request is made, the DU record will not be recovered. When contacts (voice/ /chat) are created, an EDUID is created and assigned to the contact. These EDUIDs are stored in the EDU server's memory. 80 Electronic Data Unit Server Programmer s Guide

81 DUStore Server Configuration Temporarily storing EDUIDs in the DUStore The DUStore is used by the EDU server to temporarily store certain EDUIDs as follows. The DUStore stores the EDUID and all of its information as a binary "blob" in the qw_dustore table (normally of the same IC Repository database). Note that in Oracle, the actual binary "blob" is stored in the qw_bytes table with a key to the qw_dustore table. When the EDU server receives a request (VDU.SetValues, VDU.GetValues, etc.) on a particular EDUID that is not in its memory, it will then issue a request (DUStore.Retrieve) to the DUStore to see if the EDUID is temporarily stored. If the EDUID exists in the DUStore, then it will reactivate and use it as if it was in the EDU server's memory. There are 3 different ways the EDU Server sends an EDUID to the DUStore. 1 Whenever an EDUID reaches an EDU server's Max Active Edus (vdus) configuration, the EDUID is sent to the DUStore via a DUStore.Store method. The EDU server also raises an alarm indicating that its Max Active Edus have been reached, the oldest active EDUID is the one that is sent to the DUStore. The default value for the Max Active Edus is The values depend upon how many calls can come in at your call center. 2 The EDU server has a timer called Idle Time (idletime), the default is 30mins for a contact. In pre-econtact 5.6, if a contact's EDUID reaches the Idle Time, then it is terminated and if applicable, the terminated EDUID is sent to the Report server for storage in the IC Repository database. In newer versions, including econtact 5.6, IC 5.6 and IC 6.0, the EDUID does not get terminated, instead it is sent to the DUStore and an HISTMAP.EventsIn is issued to the Report server for a VDU.auRevoir. 3 When the EDU server is shut down from econtact Manager, all the EDUIDs, in the EDU server's memory, will be sent to the DUStore via DUStore.Store. When an EDUID is sent to the DUStore, it is tagged with a Default Delete Deletion Age (days). The default is 60 days and after such days, it is deemed to be expired. The DUStore will then scan for expired EDUIDs based on Scan Interval (scaninterval) and will deleted the expired EDUIDs from the qw_dustore table based on the Deleted Per Scan (maxkill) setting. Deleting EDUIDs from the DUStore How the DUStores delete the EDUIDs: 1 The DUStore scans the expired EDUID and depending upon "Deleted per scan" parameter (The number of EDU s that are deleted each time the system is scanned for EDUs that have expired, Default is 1000.), it deletes the expired EDUIDs from the qw_dustore table. It then issues a VDU.ForceTerminate to the EDU server for each expired EDUID. The EDU server, if applicable, issues a HISTMAP.EventsIn with a VDU.end to the Report server to store each of the EDUIDs. Issue 1.0 June

82 Chapter 9 The DUStore Server 2 The number of days that the EDUIDs are held, in the absence of other information, before it is deemed to be expired depends on the "Default delete deletion age" parameter, which is the number of days that the EDUIDs are held. This value gets set when the EDUIDs are sent from the EDU server to the DUStore. The default is 60 days. The value is stored in the qw_dustore.deletedatetime field and is a specific date and random time. Difference between the EDUID stored in Report Server and DUStore The Report server stores EDUIDs that have been terminated by the EDU server. This means that either all of the clients of the EDUID have terminated their interest in the EDUID or the EDU server forces a termination of the EDUID. The EDU server issues a HISTMAP.EventsIn method for a VDU.end to the Report server. The DUStore server stores EDUIDs that are still active (there exists clients that still have interest in the EDUID), that need to be moved from the EDU server's memory, for one reason or another. The EDU seerver issues a DUStore.Store to the DUStore server and sometimes a HISTMAP.EventsIn method for a VDU.auRevoir to the Report server. Note that if and when all clients of an EDUID, stored in the DUStore, have terminated interest in the EDUID, the EDU server first retrieves the EDUID from the DUStore (DUStore.Retrieve), then the EDU server sends (HISTMAP.EventsIn for a VDU.end) the EDUID to the Report server for proper storage in the IC Repository database. Removing Records from the DUStore Database Tables Under normal processing, the DUStore data is deleted from DUStore database tables when the associated DU record is written to the interaction repository. When all interested client processes have terminated their interest in the DU record, the Report server will write the mapped DU data to the repository database tables. The DU server will then instruct the DUStore to delete the associated record from the DU Store database tables. The DUStore server can also purge forgotten or orphaned DU records from the database. The DUStore server has a configuration parameter Default delete deletion age. This parameter has a default value of 60 days. 60 days is appropriate for interactions (such as ) that are active for an extended time. Forgotten Voice and Chat interactions should be purged more quickly, for example within 1 day. When a DU record is written to the DUStore, the DUStore server adds the number of days in the deletion age parameter to the current dateand time to determine the purge date and time. A random time is added to the value as well to reduce the amount of records that will be purged at the same time due to a server shutdown. The purge alarm checkbox will cause alarms to be raised when DU Records are purged. In normal processing, DU records should not be purged, but should be deleted as part of the normal termination process. For this reason, turning this alarm on is appropriate to enable diagnostic analysis if DU records are purged. 82 Electronic Data Unit Server Programmer s Guide

83 DUStore Server Configuration When a DU record is purged, the DU server is notified to cause the DU record to be ended on the DU server. This will send the appropriate information to the Report server to then be written to the interaction repository. Troubleshooting and Testing DU records and the DU Store During the test cycles, the integration team should monitor the DUStore logs and the DUStore database tables to ensure that the DUStore server is working as expected. For example, if the DUStore is associated with a Voice only DU server and checkpointing is turned off (-1), the testing should show no activity in the DUStore. If DU records are being written to the store, the associated DU record may have been forgotten. This can be caused by workflows or IC Scripts failing to terminate interest in the DU record. It has also been seen to occur when vectoring or other switch based processing does not communicate the status of a call to the TS server. In this case, the TS server maintains interest in the DU after the interaction has actually been completed. If it is acceptable for DU records to be forgotten, take care to ensure that the DU records are purged from the DUStore in an acceptable amount of time. In a voice only configuration, the DUStore deletion day s parameter should be set to 1 day. This setting will cause the forgotten DU to be written to the repository 1 day after the DU was initially written to the DUStore. This will keep the number of DU records in the DU store at a minimum. It may also be desirable to increase the scan frequency. This will reduce the number of DUStore records that may be purged at each scan. Purging large numbers of records can cause the DU Server and the Data Server to be very busy. This can cause these servers to become unresponsive to other requesting processes. If you find that DU records have been forgotten, you may want to cause these records to be purged quicker than the scheduled purge date and time, or at a specific date and time. To turn on purging for these records, manually change the deletedatetime field on the database record using a database query tool. Changing the value to a data and time prior to the current date and time will initiate the purge on the next scan interval. The value can also be set to schedule purging to occur during light system use periods such as early in the morning or during contact center closed hours. The deleted per scan parameter will limit the number of records that the DUStore server will delete in one cycle. This can help to reduce database contention that may occur when purging records. If more records need to be purged, the server will perform the purge processing immediately after purging the prior set of records. The server will not wait until the next scan interval. It has been determined that changing this setting to eliminate problems with unresponsive DU servers does not help because processing continues until all scheduled DU records are purged. Issue 1.0 June

84 Chapter 9 The DUStore Server Parameter Setting Example The following parameters are based on the following customer situations: Customer Situation A. Element Media Channels: EDU Data: ADU Data: Expected Forgotten DU records per hour: Interaction Time with no DU activity Description Voice Only Required for backend reporting, ok to lose active DU data in case of abnormal shutdown, not ok to lose active DU data in normal server shutdown. Not used for reporting minutes EDU Server Parameter Setting Reason Checkpoint frequency -1 DU data is not required for abnormal shutdown and not worth the overhead associated with the database activity. If the server is shutdown, the active DU records will be written to the store. Idle Time 30 Double the interaction time with no activity. If an exception occurs where 30 minutes is exceeded (long queue time or long agent conversation), the DU Store will be used and the DU restored when the next activity occurs. Enable Persistance Checked We want to use the DUStore for EDU records Persistance Server Name DUStore The name of the service is used. The EDU Server will find the DUStore in the servers failover path. ADU Server Parameter Setting Reason Enable Persistance Unchecked We do not want to use the DUStore server for ADU data because the data is not used for back end reporting and will not impact the customer if lost. 84 Electronic Data Unit Server Programmer s Guide

85 DUStore Server Configuration DUStore Server Parameter Setting Reason Default delete deletion age 1 Reduced from the default of 60. This will cause forgotten DU records to be purged after 1 day. Deleted per scan 50 Reduced from the default of This setting will reduce the length of the database lock when deleting from the QW_DUStore and QW_Byte tables Scan Interval 15 Will cause purge processing to occur every 15 minutes. With 60 expected per hour, the purge will delete 15 each scan. Purge Alarm Unchecked Because we expect forgotten DU records, we do not need the alarm. Customer Situation B. Element Media Channels: EDU Data: ADU Data: Expected Forgotten DU records per hour: Interaction Time with no DU activity Description Voice and Required for backend reporting, ok to lose active DU data in case of abnormal shutdown, not ok to lose active DU data in normal server shutdown. Not used for reporting 600 voice, minutes for voice, 15 days for . EDU Server 1 (voice) Parameter Setting Reason Checkpoint frequency -1 DU data is not required for abnormal shutdown and not worth the overhead associated with the database activity. If the server is shutdown, the active DU records will be written to the store. Idle Time 30 Double the interaction time with no activity. If an exception occurs where 30 minutes is exceeded (long queue time or long agent conversation), the DU Store will be used and the DU restored when the next activity occurs. Enable Persistance Checked We want to use the DUStore for EDU records Persistance Server Name DUStoreVoice The name of the service alias is used. Issue 1.0 June

86 Chapter 9 The DUStore Server EDU Server 2 (mail) Parameter Setting Reason Checkpoint frequency -1 DU data is not required for abnormal shutdown and not worth the overhead associated with the database activity. If the server is shutdown, the active DU records will be written to the store. Idle Time 120 Set to 2 hours. This will cause any s in the queue longer than 2 hours to be written to the DUStore as well as deferred s that will not be completed within 2hours. Enable Persistance Checked We want to use the DUStore for EDU records Persistance Server Name DUStor The name of the service alias is used. ADU Server Parameter Setting Reason Enable Persistance Unchecked We do not want to use the DUStore server for ADU data because the data is not used for back end reporting and will not impact the customer if lost. DUStore Server (Voice) Parameter Setting Reason Default delete deletion age 1 Reduced from the default of 60. This will cause forgotten DU records to be purged after 1 day. Deleted per scan 50 Reduced from the default of This setting will reduce the length of the database lock when deleting from the QW_DUStore and QW_Byte tables Scan Interval 5 Will cause purge processing to occur every 2 minutes. With 60 expected per hour, the purge will delete 20 each scan. Purge Alarm Unchecked Because we expect forgotten DU records, we do not need the alarm. 86 Electronic Data Unit Server Programmer s Guide

87 DUStore Server Method Overview DUStore Server (Mail) Parameter Setting Reason Default delete deletion age 30 Reduced from the default of 60. This will cause forgotten DU records to be purged after 30 days which roughly double the maximum work time for an . Because we do not expect any forgotten mail EDU records, this should not occur. Deleted per scan 50 Reduced from the default of This setting will reduce the length of the database lock when deleting from the QW_DUStore and QW_Byte tables Scan Interval 15 Will cause purge processing to occur every 15 minutes. Purge Alarm Checked Because we do not expect forgotten DU records for , we need the alarm. DUStore Server Method Overview The following is a brief description of the methods available for use with the DUStore Server. DUStore.Store DUStore.Retrieve DUStore.Delete DUStore.DeleteByRule DUStore.Find Stores a DU in the database. Retrieves a DU from the database. Deletes a DU from the database. Purges the database of DUs. Finds zero or more the DUIDs in the database and returns the relevant DUIDs. Note: The DUStore.Store and DUStore.Retrieve methods are reserved for Avaya software. Using these methods with any other software is not supported. Issue 1.0 June

88 Chapter 9 The DUStore Server 88 Electronic Data Unit Server Programmer s Guide

89 APPENDIX A VDU.CREATE EXAMPLE The programming example shown on the following pages demonstrates an asynchronous VDU.Create method invocation. /**************************************************************** * Copyright (c) 1997, 1998 Avaya Inc, USA * All rights reserved *****************************************************************/ #include <orb.h> #include <stdio.h> /* This macro looks at the return value of vesp requests and * looks up what the error was, if any */ #define CHECK(_a)\ {\ ORBStatus _stat = (_a);\ if(_stat!= VESP_SUCCESS)\ {\ } fprintf(stderr, "ERROR: %s\n", vesp_find_error(_stat));\ exit(1);\ }\ int irequestoutstanding = 0; VDU_ID pcvduid; /* this must be static */ /* callback for the vdu create request, notice that vduid is VDU_ID* */ ORBStatus CreateResponse( Identifier interface, ORBStatus status, Environment *ev, long user_data, Session session, SeqCouple *data, VDU_ID* vduid ) { irequestoutstanding--; /* the double dereference of vduid here is important */ printf( "Created VDU: %s\n", *vduid ); return VESP_SUCCESS; } int main(int argc, char *argv[]) { 89

90 Appendix A VDU.Create Example Object client_obj; Environment ev; Session session; Request request; SeqCouple *ptseqin; /* login to vesp */ CHECK(Vesp_Login("vesp","", &client_obj)); printf( "Login.\n" ); /* create a session and set some parameters */ CHECK(Vesp_Session_Create(client_obj, &session)); Session_set_message_timeout(session, &ev, 0x1000); set_log_name("create_test.log"); printf( "Create Session.\n" ); ptseqin = vesp_couple_seq_create(); vesp_couple_seq_add_couple_values( ptseqin, "test_name", "test_value"); /* asynchronously create a VDU, use address of the pointer to VDU_ID */ CHECK( Vesp_Request( "VDU.Create", CreateResponse, 0UL, session, ptseqin, &pcvduid ) ); printf( "Create.\n" ); irequestoutstanding++; /* wait for the callback to be invoked */ while( irequestoutstanding <0 ) { Vesp_poll( 1000UL ); printf( "Polling.\n" ); } printf( "All done.\n" ); return 0; } 90 Electronic Data Unit Server Programmer s Guide

91 INDEX Symbols (checkpoint.interval) 36 (database) 37 (duindex.info1) 39 (duindex.info2) 39 (duindex.info3) 39 (duindex.lookup1) 38 (duindex.lookup2) 38 (dustore) 37 (filter) 40 (findcreatestoresearch) 38 (idletime) 36 (initialdatalength) 37 (keepevents) 38 (maxkeptrevisions) 38 (maxkills) 38 (nouserinterval) 36 (pollwait) 38 (poolgrowsize) 37 (poolsize) 37 (randomkillinterval) 37 (repackfree) 37 (reportkeepname) 40 (scaninterval) 37 (serverresetinterval) 38 (serverretryinterval) 38 (suspendinterval) 38 (vdudata.alarm.priority) 39 (vdudata.data.onlyname) 39 (vdudata.event.ifname) 39 (vdudata.eventname) 39 (vdudata.percent) 38 (vdus) 37 (watchers) 37 A ADU Data Alarms DUStore 77 VDUDATA Server 46 Alias name, reserved 35 ani 19 Application 78 Assign method 51 Assign, request to monitor edus AssignFail 33 B BadVDUInDS 33 C call_ref_id 19 Checkpoint frequency 36, Clients 25 Configuration parameters DUStore 77 edu Server 36 VDUDATA 44 Connection 78 Containers description of 21 Limitations of tokens 23 Names and tokens 21 cooperation of edu servers 12 Create a new edu 15, Create method createtime 19, 27 createtime_t 19 D data 76 Data Element Names 38 Data names, reserved 19 database 45 Database Login ID 78 Database Password 78 Database Search on Create 38 datalength 76 Deassign method 54 Default delete deletion age Default delete deletion age (Days) 78 Deleted per scan 78, deletedatetime 76 Destroy a server session 54 dnis 19 Duindex Info1 39 Duindex Info2 39 Duindex Info3 39 Duindex Lookup1 38 Duindex Lookup2 38 DumpVDU 33 91

92 Index duration 19, 27 DUStore database 75 DuStore EDU Batch Size 38 DUStore method overview list 87 DUStore.Delete 87 DUStore.DeleteByRule 87 DUStore.Find 87 DUStore.Retrieve 87 DUStore.Store 87 E edu activity 15 creation 15 data description 18 definition 15 description 15 selecting 25 server cooperation 12 termination 16, 35, EDU Data Edu Data Percent 38 edu method overview list 50 edu methods DeleteOneValue 54 DeleteSubTree 54 DeleteValues 54 GetSomeValues 60 GetSubTree 61 GetValueHistory 62 GetValuesHistory 63 SetAndTerminate 66 SetDefaultHistoryFilter 67 SetHistoryFilter 68 SetValuesExtended 70 VDU.Assign 51 VDU.Create 52 VDU.CreateExtended 53 VDU.Deassign 54 VDU.DeleteOneValue 54 VDU.DeleteSubTree 54 VDU.DeleteValues 54 VDU.EventIn 55 VDU.Find 55 VDU.FindByKey 56 VDU.FindExtended 57 VDU.FindOrCreate 58 VDU.ForwardEvent 59 VDU.GetActive 59 VDU.GetOneValue 60 VDU.GetSomeValues 60 VDU.GetSubTree 61 VDU.GetUserSessions 61 VDU.GetValueHistory 62 VDU.GetValues 62 VDU.GetValuesHistory 63 VDU.IncrValue 65 VDU.Monitor 65 VDU.RemoteWatcher 66 VDU.SetAndTerminate 66 VDU.SetAndTransfer 67 VDU.SetDefaultHistoryFilter 67 VDU.SetHistoryFilter 68 VDU.SetOneValue 69 VDU.SetValues 70 VDU.SetValuesExtended 70 VDU.Terminate 71 VDU.TerminateMine 72 VDU.Transfer 72 educational services 9 Edudata Alarm Priority 39 Edudata Data Only Name 39 Edudata Event Ifname 39 Edudata Event Name 39 eduid defined 16 structure of 17 edus resurrecting 50 Enable Persistance Enable persistance 37 Enable Reporting Interface 37 endreason 19 endtime 19 endtime (historical) 27 Event monitoring criteria boolean operators 29 defined 27 examples 31 relational operators 28 syntax 27 wildcards 29 starting stopping 26 Event stream, capturing 43 Event types 25 EventIn method 55 Events, monitoring data stream 26 Expected Forgotten DU records per hour Electronic Data Unit Server Programmer s Guide

93 Index F FailVDUCon 34 filter 40 Find method 55 FindByKey method 56, 58 FindExtended method 57 ForwardEvent method 59 G gencount 40 GetActive method 59 GetOneValue method 60 GetUserSessions method 61 GetValues method 62 H History, maintaining duplicate 41 I Idle Time 36, iidigits 20 IncrValue method 65 info1 76 info2 76 Initial Number of fields 37 Interaction Time with no DU activity L L_ucid 20 lai_dnis 20 last termination 19 listing active edus 16 Listvdu utility 16 Local adl 78 LocalVDU, as alias name 35 Log File 78 Log Level 78 Log Size 78 loginid 19 lookup1 76 lookup2 76 LostVDUEvents 34 M Max Active Edus 37 Maximum number of Revisions 38 Media Channels methods exception information 49 modifier 19 Monitor method 65 Multiple database servers, use of 41 N Name/value pairs 18 reserved names 19 No User Interval 36 NoEventSink 34 NoMeInDS 34 NoVDUOS 34 Number of Cached Edu events 38 O owner 19 owner (historical) 27 P padwidth 40 persistance 19 Persistance Server Name persistance.deletedate 19 Poll Wait 38 Pool Growth Increments 37 Pool Re-Pack (%) 37 Pool Size 37 Pre-defined data elements 19 Purge Alarm 78, Q QRepository, interaction with 12 R Random Kill Interval 37 Recall, interaction with 12 RemoteWatcher method 66 Requests, routing 50 Reset Interval 38 Resurrecting edus 50 Retry Interval 38 Routing requests 50 S Scan Interval 37, Scan Interval (min) 78 SetAndTransfer method 67 SetOneValue method 69 SetValues method 70 Special tokens 21 Issue 1.0 June

94 Index Stop monitoring events 54 suspend 19 Suspend Interval 38 system considerations 35 T Terminate method 71 TerminateMine method 72 Terminating edus, rules for 35 termination 20, 27 The 47 This 43 time 20 Tokens 21 Limitations of 23 Transfer method 72 transfercount 20, 27 V Value history 21 Values,defined 18 VDU.Assign VDU.auRevoir 25 VDU.Change 25 VDU.Create 50, 52 VDU.CreateExtended 50, 53 VDU.Deassign 50, 54 VDU.Delete 25 VDU.DeleteOneValue 50, 54 VDU.DeleteSubTree 50, 54 VDU.DeleteValues 50, 54 VDU.Drop 25 VDU.End 26 VDU.ErrVDUDATA 46 VDU.EventsIn 50, 55 VDU.Find 50, 55 VDU.FindByKey 50, 56 VDU.FindExtended 50, 57 VDU.FindOrCreate 58 VDU.ForceTerminate 50, 59 VDU.ForwardEvent 50, 59 VDU.GetActive 50, 59 VDU.GetOneValue 50, 60 VDU.GetSomeValues 50, 60 VDU.GetSubTree 51, 61 VDU.GetUserSessions 51, 61 VDU.GetValueHistory 51, 62 VDU.GetValues 51, 62 VDU.GetValuesHistory 51, 63 VDU.IncrValue 51, 65 VDU.Monitor 51, 65 VDU.NoVDUDATA 46 VDU.RemoteWatcher 51, 66 VDU.SetAndTerminate 51, 66 VDU.SetAndTransfer 51, 67 VDU.SetDefaultHistoryFilter 51, 67 VDU.SetHistoryFilter 51, 68 VDU.SetOneValue 51, 69 VDU.SetValues 51, 70 VDU.SetValuesExtended 51, 70 VDU.SlowVDUDATA 46 VDU.Terminate 51, 71 VDU.TerminateMine 51, 72 VDU.Touch 51, 72 VDU.Transfer 26, 51, 72 VDU.Watch 26 vdu_id 20, 76 VDUbad 34 vdudata.alarm.priority 45 vdudata.c 43 vdudata.data.onlyname 45 vdudata.event.ifname 44 vdudata.eventname 44 vdudata.percent 44 VDUHS, backward compatibility 41 vduhskeepname 40 VDUOS, interaction with 12 Victims 34 W Watchers 37 Wildcards Electronic Data Unit Server Programmer s Guide