Avaya DXX-1015-01 User Manual

Avaya™ Interaction Center

Release 6.0 Agent Data Unit Server Programmer’s Guide

DXX-1015-01

Issue 1.0

June 2002

Notice

Every effort was made to ensure that the information in this book was complete and accurate at the time of printing. However, information is subject to change.

Preventing Toll Fraud

“Toll fraud” is the unauthorized use of your telecommunications system by an unauthorized party (for example, a person who is not a corporate employee, agent, subcontractor, or working on your company's behalf). Be aware that there may be a risk of toll fraud associated with your system and that, if toll fraud occurs, it can result in substantial additional charges for your telecommunications services.

Avaya Fraud Intervention

If you

suspect that you are being victimized

support or assistance, call Technical Service Center Toll Fraud Intervention Hotline at +1 800 643 2353.

by toll fraud and you need technical

Providing Telecommunications Security

Telecommunications security (of voice, data, and/or video communications) is the prevention of any type of intrusion to (that is, either unauthorized or malicious access to or use of your company's telecommunications equipment) by some party.

Your company's “telecommunications equipment” includes both this Avaya product and any other voice/data/video equipment that could be accessed via this Avaya product (that is, “networked equipment”).

An “outside party” is anyone who is not a corporate employee, agent, 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) equipment or interfaces for reasons of:

• Utilization (of capabilities special to the accessed equipment)

• Theft (such as, of intellectual property, financial assets, or toll-facility

access)

• Eavesdropping (privacy invasions to humans)

• Mischief (troubling, but apparently innocuous, tampering)

• Harm (such as harmful tampering, data loss or alteration, regardless of

motive or intent)

Be aware that there may be a risk of unauthorized intrusions associated with your system and/or its networked equipment. Also realize that, if such an intrusion should occur, it could result in a variety of losses to your company (including but not limited to, human/data privacy, intellectual property, material assets, financial resources, labor costs, and/or legal costs).

Your Responsibility for Your Company's Telecommunications Security

The final responsibility for securing both this system and its networked equipment rests with you - an Avaya customer's system administrator, your telecommunications peers, and your managers. Base the fulfillment of your responsibility on acquired knowledge and resources from a variety of sources including but not limited to:

• Installation documents

• System administration documents

• Security documents

• Hardware-/software-based security tools

• Shared information between you and your peers

• Telecommunications security experts

To prevent intrusions to your telecommunications equipment, you and your peers should carefully program and configure your:

• Avaya-provided telecommunications systems and their interfaces

• Avaya-provided software applications, as well as their underlying

hardware/software platforms and interfaces

• Any other equipment networked to your Avaya products.

Avaya National Customer Care Center

Avaya provides a telephone number for you to use to report problems or to ask questions about your contact center. The support telephone number is 1-800-242-2121.

Ordering Information

Avaya Publications Center Voice: +1 800 457 1235 International Voice: 410 568 3680 Fax: +1 800 457 1764 International Fax: 410 891 0207 Email: totalware@gwsmail.com

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

Order : Document No. DXX-1015-01, 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.

Warranty

Avaya Inc. provides a limited warranty on this product. Refer to the “Limited Use Software License Agreement” or other applicable documentation provided with your package to establish the terms of the limited warranty.

Avaya Web Page

http://www.avaya.com

Trademarks

Avaya, Conversant, CustomerQ, Definity, DefinityOne, Nabnasset, Quintus, and WebQ are registered trademarks or trademarks of Avaya Inc. in the United States or other countries or both.

Portions of Avaya Interaction Center include technology used under license as listed below, and are copyright of the respective companies and/or their licensors:

ActivePerl is a trademark of ActiveState Tool Corp. This product includes software developed by the Apache Software Foundation (http://www.apache.org/). Cognos, Impr omptu 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, VSREP ORTS, 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 Cor por ation in th e United Sta tes, other coun tries , or both . Vi sual X i s 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 Ora cle ® SQL/Services are trademarks or registered trademarks of Oracle Corporation. Rogue Wave and .h++ are registered trademarks of Rogue Wave Software Inc. SourcePro is a trademark of Rogue Wave Software, Inc. Siebel is a trademark of Siebel Systems, Inc. BasicScript is a registered trademark of Summit Software Company. Sun, iPlanet, Java, Solaris JRE, J2EE, JavaServer Pages, and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. SPARC is a registered trademark of SPARC International, Inc. Products bearing SPARC trademarks are based on an architecture developed by Sun Microsystems, Inc. In3D is a trademark of Visual Insights, Inc. InstallShield® is a registered trademark and service mark of InstallShield Software Corporation in the United States and/or other countries. ORBacus is a trademark of IONA Technologies PLC. Formula One is a licensed trademark and Tidestone Technologies, Inc. Visual Components, First Impression, and VisualSpeller are registered trademarks of Tidestone Technologies, Inc. JRun is a trademark of Macromedia, Inc. in the United States and/or other countries. Intervoice is a registered trademark of Intervoice-Brite, Inc. UNIX is a registered trademark of The Open Group in the United States and other countries. Acrobat is a registered trademark of Adobe Systems.

Other product and brand names are trademarks of their respective owners.

Acknowledgment

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

BEFORE YOU BEGIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1THE ADU SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Start-up Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Cooperation of ADU Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2THE AGENT DATA UNIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Definition of an ADU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

The ADU Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

ADU Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

ADU Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

ADU Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Listing Active ADUs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

The ADUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

The ADU Data Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

ADU Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Core ADU Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Agent ADU Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Voice Data Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Queue ADU Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

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

Container Names and Special Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

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

Container Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

3EVENT MONITORING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

ADU Event Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Starting and Stopping Event Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Contents

Setting Event Monitoring Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Monitoring Criteria: Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Boolean Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Monitoring Criteria: Wildcards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Monitoring Criteria: Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

4ALARMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

5 ADU SERVER CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

System Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

ADU Server Alias Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6IDL SPECIFICATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

7 ADU SERVER METHODS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Method Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

Exception Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Routing Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Method Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

4 Agent Data Unit Server Programmer’s Guide

BEFORE YOU BEGIN

Typographical Conventions

This guide uses the following font conventions:

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

jump Blue text in online documents indicates a hypertext jump to related information. To view

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.

the related material, click on the blue text.

Notes, Tips, and Cautions

Note: A note calls attention to important information.

Tip: A tip offers additional how-to advice.

Caution: A caution points out actions that may lead to data loss or other serious problems.

Contacting Technical Support

If you are having trouble using Avaya software, you should:

1 Retry the action. Carefully follow the instructions in written or online documentation.

2 Check the documentation that came with your hardware for maintenance or hardware-related

issues.

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 crmsupport@avaya.com. 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 Documentation

Most Avaya product documentation is available in both printed and online form. However, some reference material is available only online, and certain information is available only in printed form. A PDF document with detailed information about all of the documentation for the Avaya Interaction Center is included in the 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.

Doc directory on the product CD-ROM. This PDF document is

You can also view the documentation set online at http://www.avayadocs.com.

6 Agent Data Unit Server Programmer’s Guide

Printed Documentation

You can purchase printed copies of these manuals separately. For details, see on the back of this manual’s title page.

License to Print the Electronic Documentation

Online copies of documentation are included on the CD-ROM that accompanies every software release. An Avaya customer who has licensed software (a “Licensee”) is entitled to make this online documentation available on an internal network or “intranet” solely for the Licensee's use for internal business purposes. Licensees are granted the right to print the documentation corresponding to the software they have purchased solely for such purposes.

Right-To-Print License Terms

Documents must be printed “as-is” from the provided online versions. Making changes to documents is not permitted. Documents may be printed only by any employee or contractor of Licensee that has been given access to the online documentation versions solely for Licensee's internal business purposes and subject to all applicable license agreements with Avaya. Both online and printed versions of the documents may not be distributed outside of Licensee enterprise or used as part of commercial time-sharing, rental, outsourcing, or service bureau use, or to train persons other than Licensee's employees and contractors for Licensee's internal business purposes, unless previously agreed to in writing by Avaya. If Licensee reproduces copies of printed documents for Licensee's internal business purposes, then these copies should be marked “For internal use only within <Licensee> only.” on the first page or cover (where <Licensee> is the name of Licensee). Licensee must fully and faithfully reproduce any proprietary notices contained in the documentation. The copyrights to all documentation provided by Avaya are owned by Avaya and its licensors. By printing any copy of online documentation Licensee indicates its acceptance of these terms and conditions. This license only governs terms and conditions of printing online documentation. Please reference the appropriate license agreement for terms and conditions applicable to any other use, reproduction, modification, distribution or display of Avaya software and documentation.

Educational Services

Avaya University provides excellent training courses on a variety of topics. For the latest course descriptions, schedules, and online registration, you can get in touch with us:



Through the web at http://learning2.avaya.com



Over the telephone at 800-288-5327 (within the U.S.) +001 303-406-6089 (outside of the U.S.)



Through email at Avaya.U.Helpdesk@accenture.com

Issue 1.0 June 2002 7

8 Agent Data Unit Server Programmer’s Guide

CHAPTER 1

Overview

The Agent Data Unit (ADU) Server is responsible for tracking the state of agents at the contact center. Agents are also referred to as customer service representatives, or CSRs. The term “agent” is used throughout this book to signify a customer service representative.

When an agent logs in the Avaya Interaction Center (Avaya IC), the ADU Server creates a record of the agent's session on the system. This record is called an Agent Data Unit or ADU. The ADU contains information such as the agent’s login ID, equipment number, phone type, time of login, state (InCall, WrapUp, and so on), and the time the current agent state was entered. It also contains a unique identifier (ADUID) for each ADU. The information in an ADU is used by IC Manager to generate real-time Agent Status monitors.

The ADU Server manages the ADU throughout its lifecycle. It creates new ADUs, stores open ADUs, and provides services that enable clients to interact with an agent's record. When an agent ends a session on the system, the server terminates the agent’s ADU.

HE ADU SERVER

The ADU Server is also responsible for monitoring the contents of ADUs. When ADUs are modified, the ADU Server generates events to interested clients.

Note: The ADU server is vary similar in function to the EDU (Electronic Data Unit) Server. With minor exceptions, the ADU Server functions the same way as the EDU Server.

Start-up Procedures

When Avaya IC starts up, the Avaya Toolkit starts up the ADU Server. When an agent logs in to Avaya IC, the Toolkit invokes the ADU.FindOr() method, causing the ADU Server to find or create an ADU for the agent.

If for some reason the ADU Server is not running when an agent logs in, the ADU.Create() method invocation causes the ADU Server to be started.

Chapter 1 The ADU Server

Cooperation of ADU Servers

When a new ADU Server is added to Avaya IC, existing ADU Servers must be made aware of the new server through use of the IC Manager. Refer to IC Administration Volume 1: Servers &

Domains for information on updating servers.

When the ADU 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 ADU Server, the Assign is relayed to other ADU Servers, and they watch for ADUs 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 ADUs in which they are interested. Assigning to multiple ADU Servers is unnecessary and causes numerous problems.

Every ADUID identifies the server that created it and the time at which it was created. When a client requests access to an ADU, the ADU Server that the client is using acts as a proxy to the originating ADU Server of the ADU.

10 Agent Data Unit Serve r Programmer’s Guide

CHAPTER 2

HE AGENT DATA UNIT

Definition of an ADU

When an agent logs in to Avaya IC for the first time, a record called an Agent Data Unit (ADU) is created. The ADU contains information about the agent’s activities during the session. A typical ADU might contain the time the agent logged in, the various states the agent entered (InCall, WrapUp, and so on..), and the time when the agent last entered each state.

Note: When an agent logs back into Avaya IC, a new ADU is not created. Avaya IC uses the ADU that was created at the initial login.

The information in ADUs is used to create Agent Status monitors in IC Manager.

The ADU Lifecycle

The lifecycle of an ADU is comprised of three stages: creation, activity, and termination. Each of these stages is discussed in this section.

ADU Creation

Every agent session has a corresponding ADU. When an agent logs on to Avaya IC for the first time, the Avaya Toolkit invokes the ADU.Create() method, which passes the agent’s Avaya IC login ID. In response, the ADU Server creates an ADU, assigns it a unique identifier called an ADUID, and stores the creation time and the agent’s login ID in the ADU. This ADUID is used whenever the agent logs back into Avaya IC. In other words, when the same agent logs out and back in again, the ADU server will attempt to reuse the same ADUID.

This behavior differes slightly from the way ADUIDs were created in previous versions (prior to version 5.5). In older versions, a new ADUID was created each time an agent logged in.

ADU Activity

The ADU is a real-time storage record that collects strings of text from multiple sources. During its life, the dual job of the ADU is to log the agent’s state information, as well as to collect the information ({name, value} data couples) entered by other clients or servers.

Chapter 2 The Agent Data Unit

Any application that wants to interact with an ADU has to request it by its unique identifier, the ADUID. Upon request, the ADU Server passes the ADUID out to other processes, thus enabling applications to request access to individual ADUs.

The ADU Server also honors requests to watch for ADUs that contain certain values. If any ADU matches the monitoring criteria, the ADU Server issues event messages (which contain the ADUID) to “interested” clients. (Refer to “ADU Event Monitoring,” on page 27

Typically, clients want to receive event notifications about ADUs, examine ADU contents, and modify ADU values. 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 ADU Server to return values in an ADU. Chapter 7 of this manual describes the methods supporting these activities.

ADU Termination

When an agent logs out of Avaya IC, the agent’s ADU should be closed.

Before an ADU can be closed, the ADU Server must first verify that all processes are done with it. For each ADU, the ADU Server maintains an internal list of processes that have read, transferred, or modified the ADU. Any process that invokes a method using the ADUID of the ADU is added to the list. When a client invokes the method ADU.Terminate(), the client's name is removed from the list. When the list is empty, the ADU can be terminated.

Note: In some configurations, it is possible for the agent to log out of the teleset without logging out of Avaya IC. The ADU is not closed in this case.

Safeguards are built into the ADU Server to terminate “suspicious” ADUs, in other words, those that appear to have been lost. Any ADU that has been idle for an extended period (thirty minutes, by default) is automatically terminated. (The idle time can be changed with the Idle Time configuration parameter, as described in “Configuration Parameters,” on page 37.)

If the ADU Server goes down, all ADUs are closed. For Agent Status monitors to be accurate, all users must log off and log back on again to create new ADUs.

Listing Active ADUs

You can view a list of active ADUs and the clients interested in them with the listadu utility.

To use this utility:

1 Copy

2 From the system prompt, type

listadu -iinterface -uusername -ppassword

-i interface to use (often ADU or VDU, or an alias or uuid of such a server)

listadu.exe from the Avaya IC5.x/bin directory to the directory in which the vesp.imp

and

vespidl.pk files are located, which is /etc by default.

12 Agent Data Unit Serve r Programmer’s Guide

-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 ADUID

When an ADU is created, it is automatically given an identification number (ADUID) that uniquely defines the agent's Avaya IC session. The ADUID is a 32 byte hexadecimal string partially composed of the time and date of creation of the ADU, as well as its progenitor–the software process and machine that created it. A combination of the IP and port identifies which ADU Server is the progenitor of this ADU.

The following example illustrates the structure of an ADUID.

The ADUID

ADUID = 30f4216300000000780000261f430002

Bytes

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

8–11 0000 Hex representation of a uniqueness value

12–15 0000 Reserved

16–23 78000026 Hex representation of the IP address

24–27 1f43 Hex representation of a port

28–31 0002 Reserved

Example Contents

The ADU Data Table

The data in an ADU consists of a series of sequenced {name, value} couples that represent information about an agent's session on Avaya IC. For example, the name/value pair {createtime,19970704 08:00:01} represents the time the ADU was created. The field name createtime is the name data element and 19970704 08:00:01 is the value assigned to the field. Applications gain access to data by references to field names.

Description

January 1, 1970.

Issue 1.0 June 2002 13

Chapter 2 The Agent Data Unit



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 22 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 names that Avaya IC software reserves for its own system use are listed in the following section. 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 assigned 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. An average ADU is expected to contain approximately 100 values. It can hold many more values, but additional values require more memory, which can affect system performance, and each time the ADU Server must allocate additional memory the system slows briefly.

The ADU Server sets certain name/value data pairs, such as the ADUID. Other name/value data pairs are written into the ADU by other processes. Because the ADU can accept input from a variety of sources, data could come from other servers or the agent's application. Changes to all data values are recorded, including information on who made the change and when the change was made.

ADU Contents

This section describes the ADU fields for Avaya IC in three categories: Core, Agent, and Queue. The Core category contains the ADU fields that are used by agents and queues. The Agent and Queue categories provide the ADU fields used by agents and queues respectively.

The following information may be maintained in an ADU by various system processes. Not all of these items are maintained in all environments.

Caution: The field names listed below 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. Some are read-only values to clients.

14 Agent Data Unit Serve r Programmer’s Guide

Core ADU Fields

The following ADU fields are used by both agents and queues on Avaya IC.

Field Name Description Set By

adu_id A string that uniquely identifies the ADU. ADU Server

ADU Contents

createtime The date and time the ADU was created

ADU Server

in yyyy-mm-dd hh:mm:ss format.

createtimet The time_t of the ADU creation. ADU Server

duration Historical field. ADU Server

endtime The time of the last successful

ADU Server termination of the ADU or equivalent such as removal due to idleness in hh:mm:ss format.

persistence The date and time that the EDU was last

EDU Server stored in the DUStore Server.

suspend The reason that the ADU was last

ADU Server removed from server memory. This can be any one of the following:



normal–all involved parties have suspended use of the ADU.



expired–removed from memory due to idleness.



exit–server was shut down.



overflow–removed from memory for other ADUs.



forced–removed by ForceTerminate method.

termination A string representing the reason for the

N/A termination of the ADU: normal, overflow, expired, or exit.

time Reserved for internal use. This field is

N/A inserted into each event that is set to reporting packages and is reserved for that purpose.

type The type of resource, set to “per”. Tool Kit

Issue 1.0 June 2002 15

Chapter 2 The Agent Data Unit

Agent ADU Fields

The following ADU fields are used by agents on Avaya IC.

Field Name Description Set By

auxwork.<m>.detail A code that describes the reason that the

agent entered this state.

auxwork.<m>.endtime The time that the agent exited this

AuxWork state.

auxwork.<m>.starttime The time that the agent entered the

current AuxWork state. The <m> is the increment time that agent enters into a different AuxWork state.

ceiling The maximum task load limit for the

agent.

cobject A unique representation of the client’s

last_termination The identity of the last user of the

Terminate method, used as debugging information.

load The maximum number of contacts that

can be concurrently assigned to the agent across all of the media channels.

Avaya IC in hh:mm:ss format.

loginid

The agent's Avaya IC login id.

Blender Server

Workflow Server

Tool Kit

ADU Server

Workflow Server

Tool Kit

logout The time that the agent logged off from

Avaya IC in hh:mm:ss format..

<media>.abandoned The total number of contacts that have

been abandoned since the agent logged in to the media channel. (voice, email, web)

<media>.ceiling The maximum task load limit on the

media channel.

<media>.connector The UUID of the Media Connector

Server: voice, email, or web.

<media>.contactcount The number of contacts assigned to the

agent for this media channel.

16 Agent Data Unit Serve r Programmer’s Guide

Tool Kit

Media Connector Server

Workflow Server & IC Manager

Media Connector Server

(Sheet 1 of 4)

Field Name Description Set By

ADU Contents

<media>.contactsoffered The total number of contacts that arrived

since the agent logged into this media channel. IC Manager computes handled

contacts by taking the difference between <media>.contactsoffered and <media>.abandoned.

<media>.currentload The current task load assigned to the

agent for this media channel. This is used to throttle delivery of ADUs.

<media>.load The maximum number of contacts that

can be concurrently assigned to the agent through this media channel.

<media>.loginid The login id of the agent for this media

channel.

<media>.login The time that the agent signed into the

media channel in hh:mm:ss format.

<media>.logout The time that the agent signed out of the

media channel hh:mm:ss format.

<media>.privileges This field defines the agent’s capability to

manipulate agent attributes, such as task load, for this media channel.

<media>.state The media channel state of the agent.

Normalized channel states are:



Logged-In



Logged-Out



Active



Available



Busy



Wrap-up

Media Connector

Server

Workflow Server

Workflow Server &

Blender Server

Media Connector

Server

Media Connector

Server

Media Connector

Server

Media Connector

Server &

IC Manager

Workflow Server &

Blender Server

<media>.state.<state>.total The total duration time of the agent in the

media channel state.

<media>.updatetime The time that the media channel was last

updated in hh:mm:ss format.

<media>.<n>.eduid

The Electronic Data Unit (EDU) associated with this contact where

is the contact number for the agent on this media channel.

<media>.<n>.sourcequeue The queue from which the contact was

received where

is the contact number

for the agent on this media channel.

Media Connector Server

(Sheet 2 of 4)

Issue 1.0 June 2002 17

Chapter 2 The Agent Data Unit

Field Name Description Set By

<media>.<n>.state The current media contact state.

Normalized contact states are:



Alerting



Active



On-Hold



Wrap-up



Completed

<media>.<n>.state.<state>. starttime

The time that the media channel state started.

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 ADUID, or that last used the Transfer/SetTransfer methods. (historical).

privileges This field defines the agent’s capability to

manipulate agent attributes, such as task load, for Avaya IC.

state The current agent state of the agent.

Normalized agent states are:



Logged-In



Logged-Out



Available



InitAuxWork



AuxWork

Media Connector Server

ADU Server

Workflow Server & IC Manager

Workflow Server & Blender Server

statedetail This field provides optional information

about the agent’s current state.

transfercount The number of times the ADU was

transferred since it was created. (historical)

ts. Container names beginning with ts. are

reserved for use by the Avaya Definity Telephony Server.

ts.<n>.loginid The login id of the agent for the Avaya

Definity switch.

ts.<n>.phone Agent extension, where

number for the agent on the Avaya Definity switch.

ts.<n>.ptype The Phone type–eas, acd. Definity Telephony

18 Agent Data Unit Serve r Programmer’s Guide

is the contact

Blender Server

ADU Server

Definity Telephony Server

Server

(Sheet 3 of 4)

ADU Contents

Field Name Description Set By

ts.<n>.equip Equipment number. Definity Telephony

Server

ts.<n>.starttime Time (time_t) that the client assigned to

the TS.

voice.acdname The name of the ACD the TS is serving. Telephony Server

voice.connector

voice.connectorname

Definity Telephony Server

(Sheet 4 of 4)

Voice Data Containers

The following table lists the call containers in which end point events and attributes are stored. X represents the unique identification number for each end point. Y and Z represent sequence numbers within each end point’s activities.

Note: The 6.0 style call containers are presented in this table. Call containers in the 5.5 style are still supported, and is documented in Appendix B of the Telephony Services for the Avaya Definity G3, Release 5.5 manual.

Name Value Explanation

voice.X delta time For voice.1, this is base time (should be

zero). For other cases, it is elapsed time in seconds since creation of the EDU.

voice.X.abandon reason for abandoning the call: "in

queue," "while ringing," "while on hold."

voice.X.agent_key unique database record key The key that retrieves the agent record

voice.X.conferencedest.Z phone number The destination phone number (Z) of a

voice.X.connect delta time The elapsed time in seconds between

voice.X.destination phone number Phone number of client at end point X.

voice.X.direction inbound/outbound The direction of the call to or from the

voice.X.exit_reason reason for exit: "normal,” "transfer,”

"abandon,” "other."

voice.X.holdtime.Y time in seconds Time spent on hold during hold

If the exit reason of a call end point is "abandon," this item provides additional details.

from the database.

conference call, where Z = 1, 2, 3, ...

the creation of the EDU and the time the call was connected.

agent.

The switch supplies a reason for the termination of a call end point.

instance Y.

Issue 1.0 June 2002 19

Chapter 2 The Agent Data Unit

Name Value Explanation

voice.X.leg_id unique id (UUID) Unique leg_id of the current leg of the

call.

voice.X.loginid loginid Login id of client at end point X.

voice.X.origin phone number Phone number (ANI) at other end of end

point X.

voice.X.queue delta time The elapsed time in seconds between

the creation of an EDU and the time at which the switch reports the call as queued.

voice.X.queue_number queue number Queue number configured within the

CallCenter switch as an Application Group.

voice.X.queuetime time in seconds Time reported by the switch between a

call arriving on an inbound trunk of the switch and the call being sent to an agent queue. Note: Currently, this value is always zero (0). Subsequent releases of the telephony server will supply more meaningful values.

voice.X.ringtime time in seconds Time reported by the switch between

agent phone starting to ring and agent answering the phone.

voice.X.talktime time in seconds Time reported by the switch between

agent answering the phone and agent hanging up the phone.

voice.X.transfer phone number The phone number to which the call has

been transferred.

Queue ADU Fields

The following ADU fields are used by queues on Avaya IC.

Field Name Description Set By

abandoned The total number of contacts that have

been abandoned before reaching an agent from this queue.

connector The UUID of the media connector server

responsible for the queue.

contactcount The number of contacts currently in the

queue.

Media Connector Server

(Sheet 1 of 2)

20 Agent Data Unit Serve r Programmer’s Guide

Field Name Description Set By

Containers

contactsoffered The total number of contacts received by

the queue. The number of handled contacts is computed by IC Manager by

taking the difference between contactsoffered and abandoned.

id The media channel specific id of the

queue. The id must be unique for a media channel in a specific site.

media The type of media channel over which

the queue is receiving contacts: voice, email, or web.

minimumagents The fewest number of agents that should

be assigned to one queue.

oldest The arrival time of the contact that has

been in the queue for the longest period.

priority The priority level assigned to the queue.

It can be 1 for the highest priority down to 10 for the lowest.

servicelevel The interval within which a queued

contact should be assigned to an agent on the system. This time period value varies across media channels.

Media Connector Server

servicelevelmiss The number of contacts that were not

queue_key The unique identifier for a queue, for

ttlqueuetime The period of time that contacts have

updatetime The time of the last update to the queue. Media Connector

youngest The arrival time of the contact that has

Containers

A container is a grouping of values under a common name. Containers are trees of data within an ADU.

handled during the prescribed service level time.

reporting on queue activity. This is only set when a Queue is involved in the routing of the segment. This is not set when it is a direct transfer or route to an agent, or if it is routed through Advocate.

spent in the queue.

been in the queue for the shortest period.

Media Connector Server

Server

Media Connector Server

(Sheet 2 of 2)

Issue 1.0 June 2002 21

Chapter 2 The Agent Data Unit

For example, within each ADU, the Telephony Server creates a container called ts, and within the ts container it creates a subcontainer for each of the agent's logical phones (ts.1, ts.2, and so on). Each data item pertaining to that logical phone takes a private subtree of the container–ts.1.phone, ts.1.ptype, and so on. Values for a second logical phone are written in fields ts.2.phone, ts.2.ptype, and do not interfere with values written for the first logical phone.

Note: For the Northern Telecom Meridian Link, the position ID and the IDN are considered separate logical phones, even though they share the same physical device.

The ts containers are maintained by Telephony within Avaya IC. You can create additional containers to suit your specific application.

Methods exist to return an entire container or subcontainer. Using the above example, to see all the data about the agent's first logical phone, you would use the GetSubTree() method on the ADUID and ask for “ts.1”. With the exception of the GetSubTree() and DeleteSubTree() methods, there are no special container methods. Any method that involves getting or setting data can use containerbased names.

Container Names and Special Tokens

You can specify container names or you can allow the ADU 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 created with a + in that position (for that container in that ADU). The first time it is used, it generates a 1. This means that if any client specifies a name of “code.+”, the ADU server turns it into “code.1”, but the next time any client uses “code.+” in that ADU, it expands into code.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 37), can affect subtrees created with the + token.)

22 Agent Data Unit Serve r Programmer’s Guide

! 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 will be 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 most 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”

”

Containers

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 it relates to. Otherwise, some other application might use the + token within the same container and ADU, and change the meaning of the null token unexpectedly. However, if the intent is to add data to the most recently created subcontainer no matter who created it, the null token is appropriate.

* The * is permitted only within Assign methods and is described in “Monitoring Criteria:

Wildcards,” on page 32.

Limitations of Container Syntax

The first token in a container name cannot be a special token.

When a * token has been used, special tokens other than * cannot be subsequently used.

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, as the name being generated cannot exist yet and so cannot be read..

Issue 1.0 June 2002 23

+ 51 hidden pages

Avaya DXX-1015-01 User Manual

CONTENTS

BEFORE YOU BEGIN

Overview

Start-up Procedures

Cooperation of ADU Servers

Definition of an ADU

The ADU Lifecycle

ADU Creation

ADU Activity

ADU Termination

Listing Active ADUs

The ADUID

The ADU Data Table

ADU Contents

Core ADU Fields

Agent ADU Fields

Voice Data Containers

Queue ADU Fields

Containers

Container Names and Special Tokens

Limitations of Container Syntax