avaya™ interaction center · 2002. 6. 10. · interaction center is included in the doc directory...

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

DXX-1016-02Issue 1.0

June 2002

2002, Avaya Inc.All Rights Reserved

NoticeEvery 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 telecommu-nications services.

Avaya Fraud InterventionIf 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 +1 800 643 2353.

Providing Telecommunications SecurityTelecommunications security (of voice, data, and/or video communications) is the prevention of any type of intrusion to (that is, either unauthorized or mali-cious 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, subcon-tractor, 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) equip-ment 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 intru-sion should occur, it could result in a variety of losses to your company (includ-ing 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 SecurityThe final responsibility for securing both this system and its networked equip-ment rests with you - an Avaya customer's system administrator, your telecom-munications 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 CenterAvaya provides a telephone number for you to use to report problems or to ask questions about your contact center. The support telephone number is 1-800-242-2121.

Ordering InformationAvaya Publications Center Voice: +1 800 457 1235 International Voice: 410 568 3680 Fax: +1 800 457 1764 International Fax: 410 891 0207 Email: [email protected]

Write: GlobalWare Solutions Attention: Avaya Account Manager200 Ward Hill Avenue Haverhill, MA 01835 USA

Order: Document No. DXX-1016-02, Issue 1.0, June 2002

To order product documentation online, go to http://www.avayadocs.com, click on Online Services, and select the appropri-ate product group.

WarrantyAvaya Inc. provides a limited warranty on this product. Refer to the “Limited use Software License Agreement” provided with your package.

Avaya Web Pagehttp://www.avaya.com

TrademarksAvaya, 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 licen-sors:

ActivePerl is a trademark of ActiveState Tool Corp. This product includes software developed by the Apache Software Foundation (http://www.apache.org/). 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 devel-oped 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.

AcknowledgmentThis document was written by the CRM Information Development group of Avaya

http://www.avaya.com

http://www.avayadocs.com

3

BEFORE YOU BEGIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1 OVERVIEW OF THE EDU SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11EDU Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Interaction with the IC Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Interaction with the DUStore Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Cooperation of EDU Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2 THE ELECTRONIC DATA UNIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Definition of an EDU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

The EDU Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

EDU Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

EDU Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

EDU Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Listing Active EDUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

The EDUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

The EDU Data Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Pre-defined Data Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Value History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Container Names and Special Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Limitations of Container Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

The Agent Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

3 EVENT MONITORING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25EDU Event Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Starting and Stopping Event Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Setting Event Monitoring Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Monitoring Criteria: Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

CONTENTS

4 Electronic Data Unit Server Programmer’s Guide

Contents

Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Boolean Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Monitoring Criteria: Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Monitoring Criteria: Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

4 ALARMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

5 EDU SERVER CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35System Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

EDU Server Alias Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Effect of Configuration on EDU Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

The Filter dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

6 CAPTURING THE EDU EVENT STREAM . . . . . . . . . . . . . . . . . . . . . . . . 43Capturing Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

EDUDATA Server Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

EDUDATA in a WAN Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

7 IDL SPECIFICATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

8 EDU SERVER METHODS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Exception Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Routing Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Resurrecting EDUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

EDU Method Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

9 THE DUSTORE SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

The DUStore Server Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

DUStore Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Issue 1.0 June 2002 5

Contents

EDU Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

DUStore Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

DU Store Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

DU Store Processing for Idle DU Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

DUStore Server Processing as a Backup of DU Data . . . . . . . . . . . . . . . . . . . . . . . . . 80

Temporarily storing EDUIDs in the DUStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Difference between the EDUID stored in Report Server and DUStore . . . . . . . . . . . . 82

Removing Records from the DUStore Database Tables . . . . . . . . . . . . . . . . . . . . . . . 82

Troubleshooting and Testing DU records and the DU Store . . . . . . . . . . . . . . . . . . . . 83

Parameter Setting Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

DUStore Server Method Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

A VDU.CREATE EXAMPLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91


Contents

7

BEFORE YOU BEGIN

Typographical ConventionsThis guide uses the following font conventions:

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 SupportIf 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.

Font Type Meaning

code This font signifies commands, information that you enter into the computer, or information contained in a file on your computer.

italics 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.

!


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 (http://www.avaya.com/support/qq).

� 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: 1-888-TECH-SPT (1-888-832-4778)� Direct line for international and domestic calls: 512-425-2201� Direct line for faxes: 512-719-8225

� Sending email with your question or problem to [email protected]. You may be asked to email 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 email address, please go to www.avaya.com for further information.

Product DocumentationMost 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.

Readme File

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 http://www.avayadocs.com.

http://www.avaya.com/support/qq

http://www.avaya.com

http://www.avayadocs.com

http://support.avaya.com/qq/

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 ServicesAvaya 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 http://www.avaya-learning.com� Over the telephone at 800-288-5327 (within the U.S.) +001 303-406-6089 (outside of the U.S.)� Through email at [email protected]

http://www.avaya-learning.com

11

CHAPTER 1OVERVIEW 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 OverviewTo successfully track a customer contact, such as a telephone call or an e-mail 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.

Chapter 1 Overview of the EDU Server


Interaction with the IC RepositoryThe 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 ServersWhen 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.

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.

!

Chapter 1 Overview of the EDU Server


15

CHAPTER 2THE ELECTRONIC DATA UNIT

This chapter describes the Electronic Data Unit (EDU).

Definition of an EDUEach telephone call, web chat, or e-mail 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 LifecycleThere are three stages in the lifecycle of an EDU: creation, activity, and termination. Each stage is discussed in this section.

EDU Creation

Every contact must have a corresponding EDU. Whenever an inbound call arrives at a telephone on the PBX system, a web chat or an e-mail message arrives, or a contact center agent dials out, the Telephony Server or Chat Server or Email 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.

EDU Activity

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.

Chapter 2 The Electronic Data Unit


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 e-mail 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 e-mail 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.

EDU Termination

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 EDUsYou can view a list of active EDUs and the clients interested in them with the listvdu utility.

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.

The EDUID 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 = 30f4216300000000780000261f430002

Bytes Example Contents Description

0–7 30f42163 Timestamp. Hex representation of number of seconds since 1–1–1970.

8–11 0000 Hex representation of uniqueness value

12–15 0000 Reserved



A combination of the IP and port identifies which EDU Server is the progenitor of this EDU.

The EDU Data TableEDU data consists of series of sequenced {name, value} couples that represent information about a contact. For example, the name/value pair {ani,8008863244} represents the telephone number of an incoming call. The field name “ani” is the name data element and “8008863244” 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.

16–23 78000026 Hex representation of the IP address

24–27 1f43 Hex representation of a port

28–31 0002 Reserved

Bytes Example Contents Description

Pre-defined Data Names


Pre-defined Data NamesThe 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 Description

ani Automatic Number Identification. Caller’s 10-digit telephone number.

call_ref_id 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.

createtime The date and time the EDU was created in yyyy-mm-dd hh:mm:ss format.

createtime_t The time_t of the EDU creation.

dnis Dialed Number Identification Service. Call recipient’s telephone number or extension.

duration 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.

endreason Set to “normal” for a normal termination.

endtime The time of the last Terminate method to the EDU or equivalent such as removal due to idleness.

loginid The contact center agent's Avaya IC name.

last termination The identity of the last user of the Terminate method, used as debugging information.

modifier 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.

owner The loginid or UUID of the application that created the EDUID or last used the Transfer/SetTransfer methods. (historical).

persistance The date and time that the EDU was last stored in the DUStore Server.

persistance.deletedate

The field is used to modify purging behavior of the DUStore Server.

suspend 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.



termination 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.

time Not set. This field is inserted into each event that is set to reporting packages and is reserved for that purpose.

transfercount The number of times Transfer/SetAndTransfer was used on this EDU. (historical)

vdu_id The unique ID of the EDU.

L_ucid Universal Call ID as implemented for versions 6 and beyond of the Avaya (formerly Lucent) Definity switch, CallVisor version 6.0.4.

iidigits The digits found in the “originating line information” field supplied by the switch. Used for the Avaya switch only.00–Identified line, no special treatment01–Multiparty, ANI cannot be provided02–ANI failure06–Hotel/Motel DN without room ID07–Special operator handling required20–AIOD, listed DN of PBX sent23–Coin or Non-Coin, line status unknown24–800 Service Call27–Coin Call29–Prison/Inmate Service34–Telco Operator Handled Call52–OutWATS60–TRS, Station Paid61–Type 1 Cellular62–Type 2 Cellular63–Roamer Cellular66–TRS, Hotel/Motel billed to room67–TRS, Restricted line70–Private paystation93–Virtual Private Network call

lai_dnis 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.

Field name Description

Value History


Value HistoryGenerally, 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.

ContainersA 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.



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 29.

Containers


Limitations of Container Syntax

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 Agent Container

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.

25

CHAPTER 3EVENT 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 MonitoringThe 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 When the EDU server sends the EDUs to the DUStore, it issues "VDU.auRevoir" to the report server.

The ID of the object being send to the DUStore.

VDU.Change A modification has occurred in a monitored EDU.

All affected {name, value} couples and the EDUID.

VDU.Delete Values have been deleted from the EDU.

All deleted values.

VDU.Drop 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 EDUID.

(Sheet 1 of 2)

Chapter 3 Event Monitoring


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 MonitoringThe 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.

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.

Event Description Message

(Sheet 2 of 2)

Setting Event Monitoring Criteria


Setting Event Monitoring CriteriaEDUs 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:

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=808863244"

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) 886-3244.

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.

duration termination

owner (historical) transfercount

createtime endtime (historical)



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.

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.

Relational Operators

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.



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 Operators

Boolean comparisons that return evaluations of true or false can be performed between two values. The two boolean operators are described below.

For example:

ani=508* | dnis=3315

selects all calls from the 508 area code or directed to extension 3315. 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.

Symbol Definition Description

& and Both expressions must be true.

| or True if one or both expressions are true.



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).

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).

Wildcard Definition Example

? Match one character pbx = ??? Find all couples named “pbx” which contain a three-character value.

* Find all VDUs transfercount= *

Find all EDUs that have been transferred.



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 = "8008863244" Identify any EDU containing the value "8008863244" in the field “ani”.

(ani > "2029999999") & (ani < "2040000000") Monitor all calls from the “203” area code.

ani = "203*" Monitor all calls from the “203” area code. (This is the most efficient way to do this.)

ani = "203???????" Monitor all calls from the “203” area code.

33

CHAPTER 4ALARMS

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

Another EDU Server across the WAN is unavailable. A site has been cut off. WAN features may not be available.

BadVDUInDS Emergency Bad UUID %s in DS’s list of EDU servers

Corruption in the DS has made it impossible to identify other EDU Servers for WAN work. Contact customer support (1-800-886-3244).

DumpVDU High EDU overflow, killing eldest

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)

Chapter 4 Alarms


FailVDUCon High Connection to <uuid> closed; n dropped watchers [reason]

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.

LostVDUEvents High n events lost due to network congestion or error

Event handling requests are timing out. n represents the approximate number of events that have been lost.

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

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, re-install the files and restart the EDU Server.

NoMeInDS Emergency This EDU Server is not listed in the DS for this EDU Server’s domain.

The configuration of servers and domains is incorrect. Contact customer support (1-800-886-3244).

NoVDUOS Emergency Cannot request of DUStore, %lx (losing EDUs)

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.

VDUbad High EDU %s corrupt, and cannot be resurrected

An EDU was requested but could not be restored due to database damage.

Victims High Shutdown with %u EDU%s in existence; %s. Saving to VDUOS

or

Objects discarded

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.

Alarm Name Priority Description Cause/Recommended Action

(Sheet 2 of 2)

35

CHAPTER 5EDU SERVER CONFIGURATION

This chapter contains configuration information for the EDU Server.

System ConsiderationsThe 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 NameWhen 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 TerminationSeveral 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.

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 ParametersThe 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 Description

Checkpoint frequency(checkpoint.interval)

Minimum interval period in seconds between requests to checkpoint a specified EDU into the DUStore server. A value of –1 means do not checkpoint.

Idle Time(idletime)

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.

No User Interval(nouserinterval)

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)

Configuration Parameters


Random Kill Interval(randomkillinterval)

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)

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.

Max Active Edus(vdus)

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.

Watchers(watchers)

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.

Enable Reporting Interface(database)

Should be checked if you want to enable the use of HISTADD reporting, unchecked if not. The default is checked.

Pool Size(poolsize)

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 2000.

Pool Growth Increments(poolgrowsize)

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 1024.

Initial Number of fields(initialdatalength)

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.

Pool Re-Pack (%)(repackfree)

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.

Enable persistance(dustore)

Enables the use of the DUStore Server. Check the checkbox to enable or uncheck to disable.

Label Description

(Sheet 2 of 4)



DuStore EDU Batch Size(maxkills)

The maximum number of EDUs that are sent to the DUStore Server in one set. The minimum is 1 and the default is 60.

Poll Wait(pollwait)

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.

Maximum number of Revisions(maxkeptrevisions)

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.

Number of Cached Edu events(keepevents)

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.

Retry Interval(serverretryinterval)

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.

Reset Interval(serverresetinterval)

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.

Data Element Names 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)

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.

Edu Data Percent(vdudata.percent)

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.

Database Search on Create(findcreatestoresearch)

Enables a WAN wide DUStore search on the FindOrCreate method. Check the checkbox to enable or uncheck to disable.

Duindex Lookup1(duindex.lookup1)

The name of one of the fields used to index the EDU in the DUStore Server. Used with the Find method.

Duindex Lookup2(duindex.lookup2)

The name of one of the fields used to index the EDU in the DUStore Server. Used with the Find method.

Label Description

(Sheet 3 of 4)



Duindex Info1(duindex.info1)

The name of one of the fields used to identify the EDU in the DUStore Server. Used with the Find method.





Edudata Alarm Priority(vdudata.alarm.priority)

An alarm priority used when raising an alarm related to the VDUDATA feed. Values are low, high, and emergency.

Edudata Event Name(vdudata.eventname)

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.

Edudata Event Ifname(vdudata.event.ifname)

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.

Edudata Data Only Name(vdudata.data.onlyname)

Filters events to the VDUDATA feed so they only contain this field. The parameter can be specified multiple times to allow multiple valid names.

Label Description

(Sheet 4 of 4)



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 Description

filter(filter)

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 Description

gencount 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.

padwidth 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.



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.

43

CHAPTER 6CAPTURING 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 EventsThe 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 DesignThe 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.

Chapter 6 Capturing the EDU Event Stream


EDUDATA in a WAN EnvironmentIn 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 ParametersTo 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 A value between 1 and 100

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.

vdudata.eventname event name (for example, VDU.new or VDU.end)

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)



The following represents a sample configuration for using an EDUDATA Server:

Another example configuration:

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.

vdudata.percent 100 Send events from all EDUs...

vdudata.event.name VDU.end but only their end events...

vdudata.event.ifname criticalvdudata.event.ifname hostile

and only if that event contains a data name of "critical" or "hostile"

vdudata.data.onlyname accountvdudata.data.onlyname dnisvdudata.data.onlyname ani

and strip out all data but the account, dnis and ani fields.

vdudata.vdupercent 33 Send events from approximately one third of all EDUs…

vdudata.event.name VDU.end but only their end events, in their entirety.

Parameter Setting Description

(Sheet 2 of 2)

Chapter 6 Capturing the EDU Event Stream


AlarmsThe 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 64.

47

CHAPTER 7IDL 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 );

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;

};

49

CHAPTER 8EDU 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 InformationThe EDU Server methods may return the following exception information:

Cannot use empty tokenImproper special token for this methodImproper use of a special tokenNo listing for home server for that VDUNo such name: <name>No such VDU: <vduid>No WAN VDU services in this versionNot a VDU id: <vduid>Server only attributeToo many characters in tokenToo many dot separatorsToo many names at onceUnknown errorVDU is read-onlyYou are not a serverCannot find subcontainer for that ownerFirst token must be normal hereNo match (or illegal usage)Cannot access invalidated member

Chapter 8 EDU Server Methods


Routing RequestsIn 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 EDUsUnless 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 OverviewThe following is a brief description of the methods available for use with the EDU Server.

VDU.Assign Create a session with the EDU Server.

VDU.Create Create a new EDU.

VDU.CreateExtended Create a new EDU and return the time that the EDU was created.

VDU.Deassign Destroy a session with an EDU Server.

VDU.DeleteOneValue This is equivalent to DeleteValues with a single name.

VDU.DeleteSubTree DeleteOneValue on the given name and every name in the subcontainer beneath it, cutting a branch from the tree a container represents.

VDU.DeleteValues Given a list of names, this method removes from the EDU the name and its value history, in effect making the EDU smaller.

VDU.EventsIn Adds a user-defined EDU event to an EDU.

VDU.Find Returns a list of EDUIDs that match a simple criterion.

VDU.FindByKey Finds one active local EDU based on a single search criterion.

VDU.FindExtended Identical to the Find method, but for each EDU found, it returns an EDUID and values that are indexed by the Object Store.

VDU.ForceTerminate Forces the EDU object to be deleted from memory and from the database both, so it can no longer be used.

VDU.ForwardEvent Reserved.

VDU.GetActive Finds all the active EDUs at the time the call is made.

VDU.GetOneValue Retrieves one value from an EDU.

VDU.GetSomeValues Returns all names and values matching a container name.

(Sheet 1 of 2)

VDU.Assign


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.

VDU.GetSubTree Returns all names and values in the subcontainer named by name.

VDU.GetUserSessions Returns the sessions of all clients believed to have an interest in the EDU.

VDU.GetValues Retrieves all of the values of an EDU.

VDU.GetValueHistory Returns everything that is known about the named field's values in an EDU.

VDU.GetValuesHistory Returns everything that is known about all values in an EDU.

VDU.IncrValue A useful alternative to using SetOneValue and GetOneValue to modify a value when there is a risk that two applications might conflict.

VDU.Monitor Changes Assign criteria.

VDU.RemoteWatcher Reserved.

VDU.SetAndTerminate Combines a SetValues and a Terminate.

VDU.SetAndTransfer Combines SetValues and Transfer into a single call, as these operations often occur together. (historical)

VDU.SetDefaultHistoryFilter Reserved.

VDU.SetHistoryFilter 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.

VDU.SetOneValue Sets one EDU data element.

VDU.SetValues Sets one or more EDU data elements.

VDU.SetValuesExtended Performs a SetValues, but in addition returns a parallel list of names that it created while resolving container names.

VDU.Terminate Removes the client's name from the list of interested parties for one EDU.

VDU.TerminateMine Removes the client's name from the list of interested parties for all EDUs.

VDU.Touch Touches an EDU when it is called..

VDU.Transfer Historical.

(Sheet 2 of 2)



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

Returns

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

Output 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.

VESP_SUCCESS Request was successful

VESP_ERROR Request was unsuccessful

values Initial values of the EDU, not to exceed 1023 values.

vduid Electronic Data Unit Identifier.

VDU.CreateExtended


Returns

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

Output Parameters

Returns


VESP_ERROR Internal error in EDU Server

values Initial values of the EDU, not to exceed 1023 values.


timet The time that the EDU was created.


VESP_ERROR Internal error in EDU Server



VDU.Deassign

IDL Syntax ORBStatus Deassign( ) ;

Description 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.

Returns

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

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

VDU.DeleteValues

IDL Syntax ORBStatus DeleteValues( in VDU_ID vduid, in SeqString names) ;



name Name whose values are to be deleted from the EDU.


name Name whose values are to be deleted from the EDU.

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

VDU.EventsIn

IDL Syntax ONEWAY EventsIn(in string vdu_id, in SeqEvent events);

Description This function adds an EDU event to an EDU. Values in the EDU are updated to reflect the names and values in the event.

Input Parameters

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 ) ;


names List of names whose values are to be deleted from the EDU.


event The event information. Each event must include an event name to describe the event. Requests without an event name are rejected.



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

Output Parameters

Returns

VDU.FindByKey

IDL Syntax ORBStatus FindByKey( in string name, in string value, out VDU_ID vduid ) ;

search_criteria 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 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.

matches List of VDUIDs meeting the search criteria. Note that an empty list is considered valid and returns VESP_SUCCESS.


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

Output Parameters

Returns

C Program Example

Locate a VDU having a key containing 1137.

status = Vesp_Request( "VDU.FindByKey", callback, 0x2132,session, "key", "1137", &vduid );

VDU.FindExtended

IDL Syntax ORBStatus FindExtended( in string search_criteria, in unsigned long scope, out SeqSeqCouple matches );

Description 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.

name Search key to find EDU.

value Value to match if name is found.





Input Parameters

Output Parameters

Returns

VDU.FindOrCreate

IDL Syntax ORBStatus FindOrCreate( in SeqCouple match, in SeqCouple oncreate,out string vdu_id) ;

Description 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.

search_criteria 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 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.

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.


VDU.ForceTerminate


Input Parameters

Output Parameters

Returns

VDU.ForceTerminate

IDL Syntax ORBStatus EDU.ForceTerminate(in string duid)

Description 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

Returns

C Program Example

name Search key to find EDU.

value Value to match if name is found.


VESP_SUCCESS Request was successful.

VESP_ERROR Requires values to find EDU. The match parameter may be empty.

vduseq A list of active EDUs.




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

Output Parameters

Returns

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 ORBStatus GetSomeValues( in VDU_ID vduid, in string name, out SeqCouple matches) ;

Description 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.


name EDU element to be returned.

value One returned value from the EDU.


VESP_ERROR EDUID or name not found

VDU.GetSubTree


Input Parameters

Output Parameters

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

Output Parameters

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

Output Parameters


name A name. By intent, a container name.

matches All names and values in that subcontainer.


name A name. By intent, a container or subcontainer name.

matches All names and values in that subcontainer.


users Sessions of interested clients.



Returns

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

Output Parameters

Returns

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 ORBStatus GetValueHistory( in string vduid, in string name,

out SeqString values, out SeqString when, out SeqString who) ;

Description 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.



values A sequence to contain EDU information.


VESP_ERROR EDUID was not found

VDU.GetValuesHistory


Input Parameters

Output Parameters

Returns

VDU.GetValuesHistory

IDL Syntax ORBStatus GetValuesHistory( in VDU_ID vduid, in unsigned long flags, out SeqLong headers, out SeqString names, out SeqSeqSeqString values) ;

Description 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).

vduid An EDUID of an existing EDU.

name The name of a field.

values A list of values to which the named field has been set.

when When the field was set to each value, time_t string.

who The login ID (consistent with EDU.GetValuesHistory) of the client that set each value.





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:

Input Parameters

Output Parameters

Returns

header[0] = VDU_GSGETVALUE; //first subelement is the text

header[1] = VDU_GSGETTIME; //second is time

header[2] = VDU_GSGETWHO; //third is who

names[?] = “quark”; //one of the names returned will be quark

values[?][0][0] = “truth”; //values[13] is parallel to names[13], and the //first value that was set was “truth”

values[?][0][1] = “8145264302”; //the time_t it was set (11:37:00am)

values[?][0][2] = “Scott”; //Scott set it

values[?][1][0] = “charm”; //next value set was “charm”

values[?][1][1] = “8145264362”; //set at this time

values[?][1][2] = “Jane”; //by this loginid

vduid An EDUID of an existing EDU.

flags 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

headers A list of VDU_GSGET values.

names A list of EDU data names.

values 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).



VDU.IncrValue


VDU.IncrValue

IDL Syntax ORBStatus IncrValue( in VDU_ID vduid, in string name, in long incr, out string newvalue ) ;

Description 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

Output Parameters

Returns

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.


name The name of the EDU element to change or create.

incr Increment value.

newvalue The new value of the element, after the increment.


VESP_ERROR EDU not found, or the element cannot be changed



Input Parameters

Returns

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:

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

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.


VESP_ERROR Invalid monitor criteria

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


data Values to be set, not to exceed 1023 values.

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

Returns

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.


to A string representing the receiving client.

values A list of names and values to apply to the EDU, not to exceed 1023.


VESP_ERROR EDU not found, set failed, or client not a valid string



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:

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:

The end event (VDU.End) cannot be filtered out. It must be included in the stored EDU.

Input Parameters

HS_NOSTART (unsigned short)0x01 Do not record new events

HS_NOCHANGE (unsigned short)0x02 Do not record change events

HS_NOTRANSFER (unsigned short)0x04 Do not record transfer events

HS_NOUSER (unsigned short)0x08 Do not record user-defined events

HS_NODELETE (unsigned short)0x10 Do not record delete events

HS_NOSTART (unsigned short)0x01 Do not record new events

HS_NOCHANGE (unsigned short)0x02 Do not record change events

HS_NOTRANSFER (unsigned short)0x04 Do not record transfer events

HS_NOUSER (unsigned short)0x08 Do not record user-defined events

HS_NODELETE (unsigned short)0x10 Do not record delete events

vduid Voice Data Unit Identifier.

mask Permission bits to be set.

VDU.SetOneValue


Returns

C Program Example

Vesp_Request_Sync("VDU.SetHistoryFilter", /* method identification */&ev, /* environment pointer */session, /* session object */

&request, /* pntr to pntr to requeststructure */

vduid, /* a vdu id */HS_NOUSER /* The permission bit to be set

for this VDU */ );

/* check ev for errors as needed */Vesp_Request_Delete(session, request);

VDU.SetOneValue

IDL Syntax ORBStatus SetOneValue( in VDU_ID vduid, in string name, in string value ) ;

Description 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:

Setting values can generate watch, change, and drop events.

Input Parameters

Returns


vduid owner

transfercount termination

createtime duration

endtime update_time


name The name of the EDU element to change or create.

value The value to be set.


VESP_ERROR EDU not found, or the element cannot be changed



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.



Input Parameters

Returns

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 ORBStatus SetValuesExtended( in VDU_ID vduid, in SeqCouple data, out SeqString newnames) ;

Description 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.4.

vduid owner


createtime duration

endtime update_time


values A sequence containing EDU information, not to exceed 1023 values.


VESP_ERROR EDU not found or values not able to be set

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.



Input Parameters

Output Parameters

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

Returns

vduid owner


createtime duration

endtime update_time


data Values to be set, not to exceed 1023.

newnames List of names created to resolve container names.


VESP_SUCCESS Request was successful, the EDU is gone

VESP_PARTIAL_SUCCESS

The EDU was not found in memory.

VESP_ERROR Specified EDU does not exist



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

Returns

VDU.Transfer

IDL Syntax ORBStatus Transfer( in VDU_ID vduid, in string to ) ;



VESP_ERROR EDU not found in memory or in the DUStore Server

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

Returns

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);


to A string representing a new client.


VESP_ERROR EDU not found, or client not a valid string

75

CHAPTER 9THE DUSTORE SERVER

OverviewAs Avaya IC has evolved to provide connectivity to multiple media channels such as voice, email, 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 emails 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 DatabaseThe 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.

Chapter 9 The DUStore Server


DUStore database table

DUStore FunctionsThe 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.

EDU Behavior

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

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 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 ConfigurationEach 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.



The following parameters are presented on the DUStore Server tab of the DUStore Server configuration:

The following configuration parameters are presented and set on the Database tab for the DUStore Server.

Label Description

Default delete deletion age (Days) 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.

Deleted per scan 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 1000.

Scan Interval (min) 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.

Local adl 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.

Purge Alarm This setting raises an alarm if a delete scan finds any EDUs that meet the criteria for deletion. Default is checked for yes.

Name Description

Application The name of the application. The default is qrepository.

Database Login ID User name with permission to write to the database. This is the DS login id, not the database login id.

Database Password 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.

Connection The name of the database connection to be used to associate the server with the database. The default is QConnections.

Log Size The maximum size for the log file. The default is 2.5 MB.

Log Level The level of information to be printed to the log. The default is 3.

Log File 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.



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.

� Email interactions often are in queue for significant periods of time. For example, the center may operate Monday through Friday, but email can arrive anytime. Email 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 email, 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.



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/email/chat) are created, an EDUID is created and assigned to the contact. These EDUIDs are stored in the EDU server's memory.



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 2048. 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.



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 email) 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.



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.



Parameter Setting Example

The following parameters are based on the following customer situations:

Customer Situation A.

EDU Server

ADU Server

Element Description

Media Channels: Voice Only

EDU Data: 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.

ADU Data: Not used for reporting

Expected Forgotten DU records per hour:

60

Interaction Time with no DU activity 15 minutes

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.


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

Customer Situation B.

EDU Server 1 (voice)


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 1000. 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.

Element Description

Media Channels: Voice and Email

EDU Data: 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.

ADU Data: Not used for reporting

Expected Forgotten DU records per hour:

600 voice, 0 email.

Interaction Time with no DU activity

15 minutes for voice, 15 days for email.



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.



DUStoreVoice The name of the service alias is used.



EDU Server 2 (mail)

ADU Server

DUStore Server (Voice)



Idle Time 120 Set to 2 hours. This will cause any emails in the queue longer than 2 hours to be written to the DUStore as well as deferred emails that will not be completed within 2hours.



DUStoreMail The name of the service alias is used.


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.



1 Reduced from the default of 60. This will cause forgotten DU records to be purged after 1 day.


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.

DUStore Server Method Overview


DUStore Server (Mail)

DUStore Server Method OverviewThe following is a brief description of the methods available for use with the DUStore Server.

Note: The DUStore.Store and DUStore.Retrieve methods are reserved for Avaya software. Using these methods with any other software is not supported.



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 email. Because we do not expect any forgotten mail EDU records, this should not occur.


Scan Interval 15 Will cause purge processing to occur every 15 minutes.

Purge Alarm Checked Because we do not expect forgotten DU records for email, we need the alarm.

DUStore.Store Stores a DU in the database.

DUStore.Retrieve Retrieves a DU from the database.

DUStore.Delete Deletes a DU from the database.

DUStore.DeleteByRule Purges the database of DUs.

DUStore.Find Finds zero or more the DUIDs in the database and returns the relevant DUIDs.

89

APPENDIX AVDU.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* */ORBStatusCreateResponse( 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;

}intmain(int argc, char *argv[]) {

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;

}

91

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

AADU Data

84–85Alarms

DUStore 77VDUDATA Server 46

Alias name, reserved 35ani 19Application 78Assign method 51Assign, request to monitor eDUs 25–26

AssignFail 33

BBadVDUInDS 33

Ccall_ref_id 19Checkpoint frequency 36, 84–86Clients 25Configuration parameters

DUStore 77eDU Server 36VDUDATA 44

Connection 78Containers

description of 21Limitations of tokens 23Names and tokens 21

cooperation of eDU servers 12Create a new eDU 15, 52–53Create method 52–53createtime 19, 27createtime_t 19

Ddata 76Data Element Names 38Data names, reserved 19database 45Database Login ID 78Database Password 78Database Search on Create 38datalength 76Deassign method 54Default delete deletion age 85–87Default delete deletion age (Days) 78Deleted per scan 78, 85–87deletedatetime 76Destroy a server session 54dnis 19Duindex Info1 39Duindex Info2 39Duindex Info3 39Duindex Lookup1 38Duindex Lookup2 38DumpVDU 33

INDEX


Index

duration 19, 27DUStore database 75DuStore EDU Batch Size 38DUStore method overview list 87DUStore.Delete 87DUStore.DeleteByRule 87DUStore.Find 87DUStore.Retrieve 87DUStore.Store 87

EeDU

activity 15creation 15data description 18definition 15description 15selecting 25server cooperation 12termination 16, 35, 71–72

EDU Data84–85

Edu Data Percent 38eDU method overview list 50eDU methods

DeleteOneValue 54DeleteSubTree 54DeleteValues 54GetSomeValues 60GetSubTree 61GetValueHistory 62GetValuesHistory 63SetAndTerminate 66SetDefaultHistoryFilter 67SetHistoryFilter 68SetValuesExtended 70VDU.Assign 51VDU.Create 52VDU.CreateExtended 53VDU.Deassign 54VDU.DeleteOneValue 54VDU.DeleteSubTree 54VDU.DeleteValues 54VDU.EventIn 55VDU.Find 55VDU.FindByKey 56VDU.FindExtended 57VDU.FindOrCreate 58VDU.ForwardEvent 59VDU.GetActive 59VDU.GetOneValue 60

VDU.GetSomeValues 60VDU.GetSubTree 61VDU.GetUserSessions 61VDU.GetValueHistory 62VDU.GetValues 62VDU.GetValuesHistory 63VDU.IncrValue 65VDU.Monitor 65VDU.RemoteWatcher 66VDU.SetAndTerminate 66VDU.SetAndTransfer 67VDU.SetDefaultHistoryFilter 67VDU.SetHistoryFilter 68VDU.SetOneValue 69VDU.SetValues 70VDU.SetValuesExtended 70VDU.Terminate 71VDU.TerminateMine 72VDU.Transfer 72

educational services 9Edudata Alarm Priority 39Edudata Data Only Name 39Edudata Event Ifname 39Edudata Event Name 39eDUID

defined 16structure of 17

eDUsresurrecting 50

Enable Persistance 84–86Enable persistance 37Enable Reporting Interface 37endreason 19endtime 19endtime (historical) 27Event monitoring

criteriaboolean operators 29defined 27examples 31relational operators 28syntax 27wildcards 29

starting 25–26stopping 26

Event stream, capturing 43Event types 25EventIn method 55Events, monitoring data stream 26Expected Forgotten DU records per hour

84–85


Index

FFailVDUCon 34filter 40Find method 55FindByKey method 56, 58FindExtended method 57ForwardEvent method 59

Ggencount 40GetActive method 59GetOneValue method 60GetUserSessions method 61GetValues method 62

HHistory, maintaining duplicate 41

IIdle Time 36, 84–86iidigits 20IncrValue method 65info1 76info2 76Initial Number of fields 37Interaction Time with no DU activity 84–85

LL_ucid 20lai_dnis 20last termination 19listing active eDUs 16Listvdu utility 16Local adl 78LocalVDU, as alias name 35Log File 78Log Level 78Log Size 78loginid 19lookup1 76lookup2 76LostVDUEvents 34

MMax Active Edus 37Maximum number of Revisions 38Media Channels

84–85methods

exception information 49modifier 19Monitor method 65Multiple database servers, use of 41

NName/value pairs 18

reserved names 19No User Interval 36NoEventSink 34NoMeInDS 34NoVDUOS 34Number of Cached Edu events 38

Oowner 19owner (historical) 27

Ppadwidth 40persistance 19Persistance Server Name 84–86persistance.deletedate 19Poll Wait 38Pool Growth Increments 37Pool Re-Pack (%) 37Pool Size 37Pre-defined data elements 19Purge Alarm 78, 85–87

QQRepository, interaction with 12

RRandom Kill Interval 37Recall, interaction with 12RemoteWatcher method 66Requests, routing 50Reset Interval 38Resurrecting eDUs 50Retry Interval 38Routing requests 50

SScan Interval 37, 85–87Scan Interval (min) 78SetAndTransfer method 67SetOneValue method 69SetValues method 70Special tokens 21


Index

Stop monitoring events 54suspend 19Suspend Interval 38system considerations 35

TTerminate method 71TerminateMine method 72Terminating eDUs, rules for 35termination 20, 27The 47This 43time 20Tokens 21

Limitations of 23Transfer method 72transfercount 20, 27

VValue history 21Values,defined 18VDU.Assign 50–51VDU.auRevoir 25VDU.Change 25VDU.Create 50, 52VDU.CreateExtended 50, 53VDU.Deassign 50, 54VDU.Delete 25VDU.DeleteOneValue 50, 54VDU.DeleteSubTree 50, 54VDU.DeleteValues 50, 54VDU.Drop 25VDU.End 26VDU.ErrVDUDATA 46VDU.EventsIn 50, 55VDU.Find 50, 55VDU.FindByKey 50, 56VDU.FindExtended 50, 57VDU.FindOrCreate 58VDU.ForceTerminate 50, 59VDU.ForwardEvent 50, 59

VDU.GetActive 50, 59VDU.GetOneValue 50, 60VDU.GetSomeValues 50, 60VDU.GetSubTree 51, 61VDU.GetUserSessions 51, 61VDU.GetValueHistory 51, 62VDU.GetValues 51, 62VDU.GetValuesHistory 51, 63VDU.IncrValue 51, 65VDU.Monitor 51, 65VDU.NoVDUDATA 46VDU.RemoteWatcher 51, 66VDU.SetAndTerminate 51, 66VDU.SetAndTransfer 51, 67VDU.SetDefaultHistoryFilter 51, 67VDU.SetHistoryFilter 51, 68VDU.SetOneValue 51, 69VDU.SetValues 51, 70VDU.SetValuesExtended 51, 70VDU.SlowVDUDATA 46VDU.Terminate 51, 71VDU.TerminateMine 51, 72VDU.Touch 51, 72VDU.Transfer 26, 51, 72VDU.Watch 26vdu_id 20, 76VDUbad 34vdudata.alarm.priority 45vdudata.c 43vdudata.data.onlyname 45vdudata.event.ifname 44vdudata.eventname 44vdudata.percent 44VDUHS, backward compatibility 41vduhskeepname 40VDUOS, interaction with 12Victims 34

WWatchers 37Wildcards 29