Sie sind auf Seite 1von 207

INTERACTION

CENTER HANDLER
DEVELOPMENT

CLASS MANUAL

www.inin.com/education 4.0 072914 2017, Interactive Intelligence, Inc.


Copyright and Trademark Information
Interactive Intelligence, Interactive Intelligence Customer Interaction Center, Interaction
Administrator, Interaction Attendant, Interaction Client, Interaction Designer, Interaction Tracker,
Interaction Recorder, Interaction Mobile Office, Interaction Center Platform, Interaction Monitor,
Interaction Optimizer, and the Spirograph logo design are registered trademarks of Interactive
Intelligence, Inc. Customer Interaction Center, EIC, Interaction Fax Viewer, Interaction Server, ION,
Interaction Voicemail Player, Interactive Update, Interaction Supervisor, Interaction Migrator, and
Interaction Screen Recorder are trademarks of Interactive Intelligence, Inc. The foregoing products
are 1997-2017 Interactive Intelligence, Inc. All rights reserved.

Interaction Dialer and Interaction Scripter are registered trademarks of Interactive Intelligence, Inc.
The foregoing products are 2000-2017 Interactive Intelligence, Inc. All rights reserved.
Messaging Interaction Center and MIC are trademarks of Interactive Intelligence, Inc. The foregoing
products are 2001-2017 Interactive Intelligence, Inc. All rights reserved.

Interaction Director is a registered trademark of Interactive Intelligence, Inc. e-FAQ Knowledge


Manager and Interaction Marquee are trademarks of Interactive Intelligence, Inc. The foregoing
products are 2002-2017 Interactive Intelligence, Inc. All rights reserved.

Interaction Conference is a trademark of Interactive Intelligence, Inc. The foregoing products are
2004-2017 Interactive Intelligence, Inc. All rights reserved.

Interaction SIP Proxy and Interaction EasyScripter are trademarks of Interactive Intelligence, Inc. The
foregoing products are 2005-2017 Interactive Intelligence, Inc. All rights reserved.

Interaction Gateway is a registered trademark of Interactive Intelligence, Inc. Interaction Media


Server is a trademark of Interactive Intelligence, Inc. The foregoing products are 2006-2017
Interactive Intelligence, Inc. All rights reserved.

Interaction Desktop is a trademark of Interactive Intelligence, Inc. The foregoing products are
2007-2017 Interactive Intelligence, Inc. All rights reserved.

Interaction Process Automation, Deliberately Innovative, Interaction Feedback, and Interaction SIP
Station are registered trademarks of Interactive Intelligence, Inc. The foregoing products are 2009-
2017 Interactive Intelligence, Inc. All rights reserved.

Interaction Analyzer is a registered trademark of Interactive Intelligence, Inc. Interaction Web Portal
and IPA are trademarks of Interactive Intelligence, Inc. The foregoing products are 2010-2017
Interactive Intelligence, Inc. All rights reserved.

Spotability is a trademark of Interactive Intelligence, Inc. 2011-2017. All rights reserved.


Interaction Edge, CaaS Quick Spin, Interactive Intelligence Marketplace, Interaction SIP Bridge,
and Interaction Mobilizer are registered trademarks of Interactive Intelligence, Inc. Interactive
Intelligence Communications as a Service and Interactive Intelligence CaaS are trademarks or
service marks of Interactive Intelligence, Inc. The foregoing products are 2012-2017 Interactive
Intelligence, Inc. All rights reserved.

Interaction Speech Recognition and Interaction Quality Manager are registered trademarks of
Interactive Intelligence, Inc. Bay Bridge Decisions and Interaction Script Builder are trademarks of
Interactive Intelligence, Inc. The foregoing products are 2013-2017 Interactive Intelligence, Inc. All
rights reserved.

Interaction Collector is a registered trademark of Interactive Intelligence, Inc. Interaction Decisions


is a trademark of Interactive Intelligence, Inc. The foregoing products are 2013-2017 Interactive
Intelligence, Inc. All rights reserved.

ii 2017, Interactive Intelligence, Inc.


Interactive Intelligence Bridge Server and Interaction Connect are trademarks of Interactive
Intelligence, Inc. The foregoing products are 2014-2017 Interactive Intelligence, Inc. All rights
reserved.

The veryPDF product is 2000-2017 veryPDF, Inc. All rights reserved.


This product includes software licensed under the Common Development and Distribution License
(6/24/2009). We hereby agree to indemnify the Initial Developer and every Contributor of the
software licensed under the Common Development and Distribution License (6/24/2009) for any
liability incurred by the Initial Developer or such Contributor as a result of any such terms we offer.
The source code for the included software may be found at http://wpflocalization.codeplex.com.
A database is incorporated in this software which is derived from a database licensed from Hexasoft
Development Sdn. Bhd. (HDSB). All software and technologies used by HDSB are the properties
of HDSB or its software suppliers and are protected by Malaysian and international copyright laws.
No warranty is provided that the Databases are free of defects, or fit for a particular purpose. HDSB
shall not be liable for any damages suffered by the Licensee or any third party resulting from use of
the Databases.

Other brand and/or product names referenced in this document are the trademarks or registered
trademarks of their respective companies.

DISCLAIMER
INTERACTIVE INTELLIGENCE (INTERACTIVE) HAS NO RESPONSIBILITY UNDER WARRANTY,
INDEMNIFICATION OR OTHERWISE, FOR MODIFICATION OR CUSTOMIZATION OF ANY
INTERACTIVE SOFTWARE BY INTERACTIVE, CUSTOMER OR ANY THIRD PARTY EVEN IF SUCH
CUSTOMIZATION AND/OR MODIFICATION IS DONE USING INTERACTIVE TOOLS, TRAINING
OR METHODS DOCUMENTED BY INTERACTIVE.

Interactive Intelligence, Inc.


7601 Interactive Way
Indianapolis, Indiana 46278
Telephone/Fax (317) 872-3000
www.ININ.com

iii 2017, Interactive Intelligence, Inc.


TABLE OF CONTENTS

Chapter 1: The Development Environment


Module 1.1 Handler Success 1-02

Chapter 2: Handler Basics


Module 2.1 Defining Handlers 2-02
Module 2.2 Object, Attributes, Events, and Initiators 2-06
Module 2.3 Building Handlers 2-16
Module 2.4 - Working with Basic Tools 2-30
Module 2.5 - Debugging Handlers 2-35
Module 2.6 - Dependency Viewer 2-43
Module 2.7 - Working with Subroutines 2-45
Module 2.8 - Working with Expressions 2-56

Chapter 3: Default Handlers


Module 3.1 Outbound Calls 3-02
Module 3.2 Incoming Calls 3-07

Chapter 4: Interaction Attendant


Module 4.1 Call Processing and Interaction Attendant 4-02

Chapter 5: Customizing the System


Module 5.1 Customizing Handlers 5-02
Module 5.2 Custom ACD Processing 5-06
Module 5.3 Database Tools 5-25
Module 5.4 Prompt Libraries 5-44

Chapter 6: Troubleshooting
Module 6.1 Troubleshooting 6-02

Appendix A: Handler Tools


Module A.1 Handler Tools A-02

Appendix B: Handler Pre-Class Materials


Module B.1 Interaction Center Platform Overview B-02
Module B.2 Interaction Center Architecture B-03
Module B.3 Terminology B-06
Module B.4 Introduction to Interaction Designer B-13

iv 2017, Interactive Intelligence, Inc.


Chapter
1
The Development Environment
Handler Success

www.inin.com/education 2017, Interactive Intelligence, Inc.


1.1 Handler Success

SOFTWARE DEVELOPMENT PROCESS


In order to be successful in handler development, you must have a process to follow while working
on a project.
The software industry uses several different methodologies for managing development projects,
primarily divided into the headings of Waterfall, Iterative, and Formal. Waterfall methods have
fallen into some disrepute as an Iterative model known as Agile software development becomes
more popular (for example, Extreme Programming).
For developing handlers, Interactive Intelligence recommends use of a process which essentially
combines Iterative and Waterfall methods by going through a series of steps (the Six Steps to
Handler Success) on each iteration.
We do not delineate the full set of Waterfall method steps (state requirements, analyze them,
design a solution approach, architect a software framework for that solution, develop code, test,
deploy, and maintain), but have trimmed them down to the six covered later in this chapter.
The key to success is having a defined process. Follow the defined process for every project, instead
of falling into the Cowboy method of programming where the developers do whatever they
think best, without plans, structure, review, or feedback until the final product is in the hands of
the customer.
First, we will explore the various environments involved in the development process, followed by
the process itself.

HANDLER ENVIRONMENTS

Development The development environment is where handlers are designed and built. The
development or modification of a handler does not require a connection to an IC server. All the
developer needs is a copy of Interaction Designer running on their workstation and the handlers
that they will be modifying. The developer can make the handler modifications, do an intermediate
publish, and complete the publishing process on the development IC server. Now the handler is
ready to move into the testing environment.
Testing The testing environment is where handlers are tested. The testing environment should be
as close to the production environment as possible. All Interaction Center functionality should be
available in the testing environment. Every possible scenario of the handler should be tested, which
includes both proper functionality and error handling. Only after the handler has been thoroughly
tested should it be promoted to the production environment.

1-02The Development Environment 2017, Interactive Intelligence, Inc.


Production The production environment is where the Interaction Center system interacts with users
and the outside world. Be cautious about promoting handlers to this environment because an improperly
working handler can have serious consequences on the production Interaction Center system.
Make sure that the handlers have been thoroughly tested before publishing them on the
CAUTION
production server!
This is a cyclical process. As more needs arise, handlers that are currently in the production environment
may require more customization and go back through the Development and Testing environments.

SIX STEPS TO HANDLER SUCCESS

This section offers an overview of the entire process of building and editing handlers. Reading this
section is recommended, before you begin using Interaction Designer to build or modify handlers.
Research In this step, you gather information about:
Currently used handlers
The task to be completed
The handlers you will interact with

Design Map out the functionality you plan to build and figure out how it will run with the other
handlers and subroutines. In this step, you will design the handler on paper. This design may be in one
of the following forms:
Flowcharts
Pseudocode

Build Begin creating and linking steps to perform the new functionality. In this step, you use
Interaction Designer to build the handler.
Activate When you finish building the handler or subroutine, it must be compiled and moved to the
Interaction Center server, using the automated Publishing process. Handlers and subroutines are
published through Interaction Designer. In this step, you use Interaction Designer to save, publish,
and manage the handler.
Test In this step, you run the handler on your test system and ensure that it is functioning correctly.
Promote In this step, you move the handler from the test system to the production environment.

1-03The Development Environment 2017, Interactive Intelligence, Inc.


RESEARCH

The first step in building handlers and subroutines is research. You must be familiar with the
handlers currently being used on your Interaction Center server. You will have to decide if the
handler you are planning can be integrated into a current handler, if a new handler is needed, or
if the functionality you require is already available in Interaction Attendant. Many functions that
previously required handler modifications can be accomplished in Interaction Attendant by adding
an operator.
There are several places you can look for information on the existing handlers. First, view the
contents of the Interaction Designer Help menu.
Also, review the reference and procedural topics in this Help system. The Tools help available
from the Help Topics can help you learn the function of each step in a handler or subroutine. The
procedural topics and various introductions can help you understand how handlers work.
Research the other systems the handler may interact with such as databases, LDAP directories, or
other programs.

RESEARCH PIN CODE EXAMPLE


To help you understand the six steps to handler success, we will provide an example of each stage.
PIN Code Interactive Innovative Investments wants to have a stand-alone lobby phone be
unusable for placing calls after hours to anyone unless they enter a valid PIN code. If a correct code is
entered, they will be allowed to place a call. If the caller enters an incorrect PIN, they are told the PIN
is incorrect and the call is disconnected.
Research In the research step of the process for this request, you would determine the following:
What handlers run when a call is placed from a stand-alone station phone?
Is there a customization point available there?
What hours of the day constitute after hours?
What about weekends?
What about Emergency calls?
Can this be accomplished through Interaction Attendant or Interaction Administrator?
What are correct PIN codes?

You would find this information in the Handler Help, Dependency Viewer, and by referring to any
technical specifications given to you.

1-04The Development Environment 2017, Interactive Intelligence, Inc.


DESIGN

In many cases, new functionality can be implemented within Interaction Attendant. If Interaction
Attendant cannot be used, you may need to modify an existing handler to implement the new
functionality.
If you decide to modify an existing handler or subroutine, strongly consider using the customization
points provided. Customization points ease future upgrades because they will not be overwritten.
Creating a handler If you are planning a significant addition or change in functionality, you
probably need to build a new handler. A base handler will start when an event occurs on the server
to start that handler. Most of the events that occur on the Interaction Center server already have a
handler associated with them. Unless you are adding third-party products that generate their own
unique events, you will probably build a subroutine.
An example of a piece of third-party equipment that might generate a unique event is a machine
monitor. For example: a hospital has a computer monitoring a piece of equipment. Anytime that
equipment fails, the monitoring computer creates an alarm event. This event could be passed into
Interaction Center and start a handler designed to watch for an alarm event.
Design Process Tools Before creating a handler in Interaction Designer, design the functionality
first, on a whiteboard or on paper using a flowchart or pseudocode. Try to think in terms of the
Interaction Designer tools and what groups of tools create the needed logic. Remember that creating
handlers is programming; planning at the outset saves time when you start building the handler.
Flowchart: A flowchart is a graphic or diagram which shows how a complex operation takes
place. The flowchart breaks down that operation into its smallest and simplest parts. The table
below lists some of the more common flowcharting symbols and their purposes. There are many
more flowcharting symbols to represent more functions such as database operations, printing,
calling a subroutine.

Symbol Purpose

Process Represents a process such as play a prompt, transfer a call,


disconnect a call, and so on

Connector Used at the intersection of two or more lines.

Data Represents an input/output operation, such as getting digits entered

Decision Used to evaluate a Boolean expression. This symbol has two


branches from it, a true path and a false path.

1-05The Development Environment 2017, Interactive Intelligence, Inc.


Symbol Purpose

Manual operation Represents an activity that requires human


intervention, such as lifting a handset.

Off-page connector Used when the flowchart spans more than a


single page. An integer or letter is assigned to the off-page connector
and its associated off-page connector on another page to indicate
where the logic continues.

Terminator Indicates the end of the logic for this particular program. If
this is a subroutine, control will return to the calling handler.

Pseudocode: Pseudocode is plain English wording to describe a function or program logic.


Programmers use pseudocode to talk out the logic before attempting to write the program.

DESIGN PIN CODE EXAMPLE


Let us continue our example to help you understand the six steps to handler success.
PIN Code The flow chart and pseudocode for the PIN Code handler would look like this:

Pseudocode 1
1. A call is placed from a station.
2. Is it an Emergency call?

1-06The Development Environment 2017, Interactive Intelligence, Inc.


3. If yes, return to calling handler to place the call.
4. If no, does the station name begin with Lobby?
5. If no, return to calling handler to place the call.
6. If yes, check to see if it is Saturday or Sunday.
7. If yes:
a. Prompt for PIN.
b. Capture keys entered.
c. Check for valid PIN.
d. If yes, place the call.
e. If no, play, Sorry, that is not a valid PIN and disconnect.
8. If no, is the current hour < 8 or > 16?
9. If yes:
a. Prompt for PIN.
b. Capture keys entered.
c. Check for valid PIN.
d. If yes, place the call.
e. If no, play, Sorry, that is not a valid PIN and disconnect.

Is there a tool associated with the return to the calling handler? How will the subroutine know when
to return?

BUILD

Once you have mapped out the functionality and decided to implement the logic, you are ready
to start modifying or building the handler in Interaction Designer. When building handlers, it is
important to understand the tools and their parameters that will be required for the logic.
To access Help for a tool, click the Help button on its tabs, or select a tool on the Tools page of
the Design palette and press the F1 key. The help for each tool consists of a general description
of the step, its parameters, and its exits. You can also find help on working with steps from the
contents page of the Help. It may also be helpful to view how steps are used in other handlers. Use
Dependency Viewer to find other handlers that use a specific tool.

1-07The Development Environment 2017, Interactive Intelligence, Inc.


It is not necessary to deactivate a handler before you begin editing. Any changes you make to an
FOR YOUR
INFORMATION
active handler do not take effect until you publish that handler.

ACTIVATE

Once you have finished building or modifying a handler, it must be published so that the changes
take effect. Publishing a handler is the automated process of compiling the code into a proprietary
format and placing the compiled code on the Interaction Center server.
Subroutines must be published before they can be called from other handlers. Once you have
published a new subroutine, a new subroutine tool appears on the subroutine page of the Design
Palette. Use new subroutine tool to create a new step in the handler that calls that subroutine.
There may be times when you do not want to publish your handlers on the same server on which
they were created. If so, use the intermediate publish to generate an .i3pub file. Then it can be
moved to the appropriate server and the publishing process can be completed.
When a handler is first published, you can activate it immediately. If you do not do activate it
immediately, or if the handler has been imported from another server or previously been made
inactive, activate it in the Manage Handlers notebook so it can be used in Interaction Center.

TEST

After you have published the handler, ideally to a test server, thoroughly test the functionality of
the handler you have built. If you do not have a test server, then test the handler during down time.
Never implement an untested handler or untested handler modification on a production server!
Testing is critical. Untested handlers can cause a server to malfunction.
CAUTION

1-08The Development Environment 2017, Interactive Intelligence, Inc.


PROMOTE

Only after the handler has been thoroughly tested should it be published and managed on the
production IC server.

HABITS OF SUCCESSFUL PROGRAMMERS


Always back up before making changes to the handlers
Always test your changes before applying them to a production server. Verify that they function
even if incorrect data or values are entered. All changes are significant. Even a small change can
bring a server down.
Document! Document! Document!

BASIC HANDLER BEST PRACTICES

GENERAL
Build to the right or down: Design your handlers so they start from the upper left corner and
build to the right or down. This makes your handlers easier to follow.
Use Dual Monitors and Zoom Feature: It is easier on the eyes to use dual monitors. Using the
Zoom feature allows you to view more or less of the handler as needed instead of scrolling back
and forth trying to see the whole thing.
Extend step to show whole selection step: Expand step size to show the values and the step label.
Use one Selection step instead of multiple condition steps when appropriate: One step is easier
to read and more efficient.
Avoid huge selection steps: Especially with string expressions. Selection steps can be a significant
bottleneck if used incorrectly. Selection steps evaluate expressions from the top down until an
expression resolves to true. Each selection expression is evaluated independently of any of the
previous selection expressions, so any repeated expressions will be evaluated again.
In a Selection step, place the most-often-occurring expression at the top of the list: Expressions
are evaluated from the top of the list to the bottom.
Use Hungarian Notation for Variable Names: By doing so, you can glance at a variable name and
know its data type.

DOCUMENTATION
Use File/Properties to document handler: Use the file properties window to document a handler
instead of the notes for the initiator.
Use the step notes to document the step: Use the notes area on each step to document
information regarding the intended use of the step.
Indicate changes in step label: anytime you make changes to a production handler or a handler
that someone else wrote, indicate which steps you changed by changing the step notes.
1-09The Development Environment 2017, Interactive Intelligence, Inc.
OVERALL PROJECT TIPS
Protect default handlers and customized handlers: Keep custom handlers in their own separate
directory. Write-protect the default system handlers either at the file or directory level to avoid
inadvertent changes. Store modified default system handlers separate from the default handlers
and any custom handlers. Avoid making any changes to the default handlers. If you must make
changes, use subroutines if possible. If you often make changes to certain default system
handlers, request the addition of a customization point by Interactive Intelligence development.
Reuse code across projects: Avoid naming handlers and variables and other items after clients or
projects so that you can easily reuse the handlers for other clients or projects. This is especially
true with subroutines that act like functions.
Follow good project management practices: Plan out handlers using call flow diagrams
developed in Microsoft Visio or a similar application. Make sure all paths for all options in the
call flow end with specific requirements. Make sure that the diagrams are complete, including
even minor details. Get a sign-off on the call flow scope of work before starting.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following labs in your lab manual:
Lab 1: Research and Design
Lab 2: Handler Development Precautions
Lab 3: Hello World

1-10The Development Environment 2017, Interactive Intelligence, Inc.


Chapter

Handler Basics
Defining Handlers
2
Object, Attributes, Events, and Initiators
Building Handlers
Working with Basic Tools
Debugging Handlers
Dependency View
Working with Subroutines
Working with Expressions

www.inin.com/education 2017, Interactive Intelligence, Inc.


2.1 Defining Handlers

DEFINING HANDLERS
A handler is an .ihd formatted file that is made up of individual steps that form logic.
This logic responds to events and processes them, depending on the specific event and information
passed to the handler.

Like any program, handlers perform a series of actions. Actions in the handler are graphically
represented by a step, creating a flowchart look.
Steps (or actions) are performed in an order determined by how the steps are linked together.
Each step performs a different action. This combination of actions determines what happens
when the handler runs.
Some steps start other handlers, called subroutines.

FILE STRUCTURE FOR DEFAULT HANDLERS

The Handlers folder is created on the same partition in which IC is installed during the Interaction
Center install. The handlers and associated directories can be found in the following locations:
\I3\IC\Handlers\40Handlers This is the default location of the Interaction Center handlers. It
contains all the base handlers and subroutines, including all Interaction Attendant handlers that

2-02Handler Basics 2017, Interactive Intelligence, Inc.


were installed by the system. This directory contains the .ihd files and the .i3pub intermediate
publish files. There are also several command files and lists that allow for publishing groups of
related handlers (for example, all Attendant handlers or all multi-site handlers).
\I3\IC\Handlers\Custom This folder is there for you to place any custom handlers that you create.

It is always recommended that you make copies of these folders and store them on a separate
CAUTION
machine in case a handler is deleted or damaged.

HANDLER STANDARDS
Certain design standards have been implemented at Interactive Intelligence in order to maintain a
level of quality and consistency when designing handlers. For ease of understanding, we recommend
that you follow these standards where appropriate.
Boilerplate Text Every system handlers dialog box lists customization points that are called from
within the handler. Here is an example of boilerplate text from System_IncomingCall.ihd:

Use this page to document any subroutine calls that you add to the handler.
Variables (locally scoped) For consistency in variable naming, a convention similar to Hungarian
notation is used. There is a prefix for the name of each variable that indicates the data type, in
lowercase, followed by the variable name. The following table outlines normal (basic) data type
prefixes for handler variables:

Data Type Notion Example

Integer i iCount

Numeric n nPayRate

Boolean b bSuccess

String s sName

2-03Handler Basics 2017, Interactive Intelligence, Inc.


For all data types, including those listed above, there is a corresponding list data type. For example,
there is a Mail Folder data type and a corresponding List Mail Folder data type. Any list data type
starts with an l followed by the type abbreviation (for example, lmfSysAdminAccounts).
An exception to this standard exists for variables with the data type of Call ID. In previous releases
of IC, these variables were named Call1, Call2, and so on. Now variables of the data type Call ID
are named Interaction1, Interaction2, and so on. Since the IC product lines focus on processing
interactions we spell out this data type.
Variables (globally scoped) Globally scoped variables start with g_ to denote that it is global
followed by lowercase data type indicator (e.g., g_iUsersLoggedIn).
Since handlers that access a global variable place a lock on that variable while the handler is running,
Get, Increment, and Decrement subroutines can be used to retrieve or change the value of a global
variable. By creating these handlers the lock will be on the global variable for the shortest time so
that other handlers can access it.
Handler Names Handler names are descriptive of their task and typed in mixed case capitalizing
the first character of each word (e.g., PlayTelephoneNumber.ihd).
Subroutines All input and output parameters to a subroutine are named p_<variable name> (e.g.,
p_sRemoteTN). This standard format allows anyone viewing the handler to identify this variable as a
parameter to a subroutine.
Attributes Any new attributes should be in uppercase beginning with ATTR_ (e.g., ATTR_
HELLOWORLD).
Prompts Prompts start with <name>_<Language abbreviation> (e.g., HELLOWORLD_ en-US).
General Layout It is import that the layout of a handler is clean and easy to follow. Handlers with
bunched steps, links that are difficult to follow because they flow under steps, and unused tools left in
the handler are hard for others to read and debug. These handlers are more likely to contain errors. Logic
flow is up to the individual handler designer, but follow these general guidelines concerning layout:
Never allow links to flow through a step. You can always make space so that links do not flow
though a step. Create anchors link around a step.
Do not bunch steps together, make sure that there is plenty of white space between the steps. If
you are modifying a handler and need more room for new steps, drag out the other tools to make
space. You can zoom out to 50% or lower so you can easily grab groups of steps.
Fill out all label fields on each step. For example, assignment steps should have the variable name
they are assigning in the label (e.g., sUserName). Condition steps should give some indication as
to what is being evaluated (e.g., Success=TRUE?, iCount >= # of Users?, and so on). Assignment
and condition steps can also use the Auto Labeling feature of Designer.
Make sure that the Step Name and Step Label are visible. The only exceptions to this rule might
be the selection step that could contain wide case elements, but can be widened completely in
most cases.
Align your steps. If you have a number of steps that flow left to right, up and down, align them
so they make the handler more easily readable. Use the align buttons on the button bar. It takes
only a moment to select a group of steps and click an align button.
DOCUMENT! Add notes as needed, especially if you are doing something unusual. Explain
why you are performing specific actions (for example, creating a customization for a specific
piece of software or a special situation). Put the word NOTE in the label in all caps (for example,
NOTE:<label>) to draw attention to it. It could save hours of debugging to determine the
purpose of the step.
When finished developing a handler, eliminate all unused variables by selecting them in the
Variables Palette and deleting them.

2-04Handler Basics 2017, Interactive Intelligence, Inc.


Review Questions
Complete the review questions for this module in your study guide.

Labs
There are no labs associated with this module.

2-05Handler Basics 2017, Interactive Intelligence, Inc.


2.2 Objects, Attributes, Events, and Initiators

OBJECTS

An object is an entity in Interaction Center on which actions can be performed. It is uniquely


identified with an object ID. Objects also have attributes that can be used in handlers.

TYPES OF OBJECTS
Call Objects Whenever a call comes in to the Interaction Center, a new call object is created. That call
object can have actions performed on it. For example, it can be transferred or placed in a user queue.
Chat Objects In IC, chat objects are online, real-time, typed conversations between an Interaction
Center user and a remote chat participant browsing a website. Chat sessions are similar to telephone
conversations, except that the information is typed and not spoken.
Email Objects Email objects are created when an email message comes into an ACD workgroup.
Generic Objects A generic object is typically a third-party interaction, such as a proprietary web
chat, that is ACD routed by an Interaction Center server. When a request comes in, Interaction
Designers Create Generic Object tool is used to specify the name of an ACD or agent queue. The tool
step assigns a generic object ID to the object, which is similar to a call object ID. The generic object ID
is used by the Interaction Center to reference the object when it is routed from an ACD queue to the
agent. The object itself is stored in Queue Manager.
There are many other types of objects, such as user queue objects and fax objects.
FOR YOUR
INFORMATION

ATTRIBUTES

Attributes are pieces of information about something. For instance, in the case of a person,
attributes include hair color, weight, eye color, and so on. A more pertinent example would be the
case of an inbound call into IC. The call comes into the system with attributes which can be read,
changed, and added to by system processes and handlers. There are two fundamental types of
attributes in IC:
Object Attributes Telephone calls, chat sessions, and email are objects processed by the
Interaction Center. Object attributes are pieces of information about that object that travel with
it throughout the Interaction Center. Developers can define generic objects that have custom
attributes. Developers can define custom attributes for any type of object. Telephone calls, chat
2-06Handler Basics 2017, Interactive Intelligence, Inc.
sessions, email, and generic objects are entities that have attributes associated with them.
Inbound calls have ANI/DNIS information, Station Name, and other attributes that move with a call
EXAMPLE
and can be extracted for use.
If you need them, you can also add your own user-defined attributes. You can add a call object
attribute with the Set Attribute tool, and you can retrieve its value with the Get Attribute tool.
Other objects have similar tools for working with attributes.
Directory Service Attributes Directory Services (DS) attributes cache information about
Directory Service keys in the Windows Registry. The information stored in DS attributes are the
values that are set in Interaction Administrator.
Examples of handler tools used to access and work with DS attributes include: Get Ds Attr, Get Ds
Attrs, and Lookup toolsteps, and the corresponding Put Ds toolsteps under the System tab of the
Design Palette.
Whereas DS attributes reside in Directory Services and can be retrieved at any time, object
FOR YOUR
INFORMATION
attributes travel with an object as long as it is in the system. When the object is no longer in the
system, the attributes are gone as well.

OBJECT ATTRIBUTES

A variety of entities create attributes, including the Interaction Center itself. For example, the
Telephony Services subsystem creates many default call object attributes when a call object is
created. Handlers, Interaction Center applications, and programs developed using various system
APIs can create and modify attributes.
Attributes are name/value pairs. To retrieve the value of a call or chat object attribute, you specify
an attribute name. The value returned for an attribute is usually string data. However, chat and call
attributes can contain 32-bit binary data in DWORD format. Email objects return data that is stored
in Interaction Designers list variable format.
Object attributes can be thought of as temporary storage. They only last as long as the object. Each
type of object (call, chat, email, and so on) has its own set of attributes.

OBJECT ATTRIBUTE NAMES


Attribute names are not case-sensitive. EIC_StationName and eic_stationname refer to the
same attribute. Although case is insensitive, the name of an attribute provides a clue to how the
attribute is used.
Attributes names that begin with EIC_ belong to attributes that are primarily used by
Interaction Desktop to display information about an object.
Attributes names that do not begin with EIC_ belong to attributes that are primarily used by
handlers or chat objects.
Attributes names that end with Raw belong to attributes that contain original, unprocessed
values. These attributes are logged for reporting purposes.
User created attributes should be named ATTR_<ATTRIBUTE NAME> (e.g., ATTR_
ACCOUNTCODE).

2-07Handler Basics 2017, Interactive Intelligence, Inc.


OBJECT ATTRIBUTE TOOLS

CALL AND CHAT OBJECT TOOLS


The same tools are used for call and chat objects to retrieve and assign attribute values.

Tool Description

This step obtains an attribute from a call or chat object and


Get Attribute
assigns that attribute as the value of a variable.

Get Attributes Retrieves a list of call attributes and their values.

This step assigns a new attribute to a telephone or chat call, and


Set Attribute
assigns the value of that newly assigned object attribute.

Set Attributes Assigns one or more values to a list of one or more call attributes.

EMAIL OBJECT TOOLS

Tool Description

Email Interaction Get Message This tool gathers the email attributes for the specified email object.

Email Interactive Update


This tool sets the email attributes for the specified email object.
Message

GENERIC OBJECT TOOLS

Tool Description

Get Generic Object Attribute Retrieves one attribute from a specified object.

Set Generic Object Attribute Sets the value of an attribute for a specified object.

These tools cannot be used to retrieve values of attributes for Directory Services keys. To get
FOR YOUR
INFORMATION
those values, use the Get DS Attr, Get DS Attrs, or Lookup tools located under the System tab in
the Design Palette.

EVENT

Events correspond to actions that are associated with objects. For example, when Telephony
Services receives an incoming call, it creates a call object with a unique Object ID. Telephony
Services then generates an event called Incoming Call. Every time an IC subsystem performs an
action associated with an object, it generates an event. Some handler tools also generate events,
2-08Handler Basics 2017, Interactive Intelligence, Inc.
such as ACD Initiate Processing which generates an ACDProcessQueueItem event, and Blind
Transfer which generates a Call to Non-System Queue event. Hardware or software that is not part
of the Interaction Center system can generate events, such as a security card reader or a computer
that monitors a piece of equipment.
Events serve two purposes in Interaction Center. Events:
Start an instance of a handler An event can tell Interaction Processor to start an instance of a
handler designed to respond to that event. When Telephony Services generates an Incoming Call
event, the Notifier tells Interaction Processor that the event has occurred. Interaction Processor
starts an instance of any handlers configured to run when the Incoming Call event occurs.
Carry information about an object An event can carry information about the object. For
example, an event generated by an incoming call carries information about that call, such as
the caller ID and the name of the line that the call is coming in on. This information is stored as
attributes. These attributes can be used by the handler to make decisions about what to do with
the object.

Examples of events:
Incoming Call
Disconnected Call
Station Off Hook
Incoming Email

INITIATORS
An initiator is always the first step in a handler. It tells Interaction Processor which event starts an
instance of that handler.
Here is an analogy: You are stopped at a traffic light and the light turns green. The changing of the
light is an event that starts a series of actionsyou press down on the accelerator, the car moves
forward, and so on.
In Interaction Center, the action caused by the event depends on an initiator. When one of the
modules in Interaction Center, such as Telephony Services, generates an event, that event is
seen by the Notifier. Notifier then tells other modules about that event. One of these modules is
Interaction Processor where the handlers are registered. When the Notifier tells the Interaction
Processor about an event, Interaction Processor starts an instance of a handler.
When you publish a handler, the handlers initiator tells Interaction Processor which event to watch
for. An event is something that happens to an object. For example, a call (object) can be sent to voice
mail (event). If you configure an initiator in a handler to start when calls are sent to voice mail, then
Interaction Processor starts that handler any time it is notified of that event.

2-09Handler Basics 2017, Interactive Intelligence, Inc.


TYPES OF INITIATORS

There are two types of initiators in Interaction Center:


Event Initiators Event driven initiators start an instance of a handler when an event in Interaction
Center matches the initiators properties.
Subroutine Initiators Subroutine initiators start an instance of a subroutine handler from another
handler. Subroutine initiators do not use events. Instead, a subroutine call step, contained in a
handler, initiates the jump from a handler to a subroutine.

IN CLASS EXERCISE
Find the following handlers in Interaction Center and determine if they are event or subroutine initiated.

Handler Type of Initiator

SystemIVR.ihd

System_CallOfferingNonSystemQueue.ihd

System_StationOffHook.ihd

InteractionAttendantEntryPoint.ihd

ACDAvailableAgent.ihd

CustomAnswer.ihd

SystemIVRTransfer.ihd

2-10Handler Basics 2017, Interactive Intelligence, Inc.


HANDLER INSTANCES

When the same event occurs multiple times (such as an Incoming Call), each event spawns an
instance of the same handler. This behavior allows Interaction Center to handle many of the same
type of events at the same time.
When the first event is recognized in Interaction Center Notifier alerts the Interaction Processor
that there is a particular event happening. The Interaction Processor matches the event properties
with the properties of an initiator and spawns an instance of a handler.
When a second event of the same type happens The exact same process happens again except
there is a second instance of the handler spawned. These two instances can run simultaneously.

CHANGING AN INITIATOR

2-11Handler Basics 2017, Interactive Intelligence, Inc.


To add an initiator to a new handler or to change an existing initiator, go to the File menu and select
Change Initiator. This action opens the Available Initiators dialog box in which you can select any existing
initiator, including the Subroutine initiator. There are a few guidelines when working with initiators:
There can only be one initiator per handler.
If there is an existing initiator, it will be replaced when you change the initiator.
Do not use the same initiator for more than one primary handler.
Monitor handlers may use the same initiator.

EVENT INITIATOR PROPERTIES

On the Initiator Properties page, there are three settings for most initiators. (HTML, Timer, and
Subroutine initiators are different.) The combination of these three settings determines when
Interaction Processor will start an instance of a handler containing that initiator. These three
settings are described below:
Notification Object Type An object type is an entity that can be used or managed by Interaction
Center. Examples of some of these objects include calls, chat sessions, and faxes. Queues are also
objects, including user, station, workgroup, and line queues. The Notification Object Type of an
initiator cannot be changed.
Object ID One property for an instance of an object is a unique object ID. This object ID is a unique
number that differentiates one instance of an object from another. In most cases, you should leave
this setting to {all} so that the handler starts for an object with any Object ID.
Every call that comes through Interaction Center has a unique Object ID. The default value for this
EXAMPLE
setting is {all} to allow an initiator to start for every occurrence of an event to an object. In most
initiators, this setting cannot be changed.
Notification Event An event is an action that is associated with an object. Examples of some of the
events that occur on a call object are transfer, send to voice mail, and new outgoing call request.
Events also carry information that can be retrieved by the initiator for use in the handler.

2-12Handler Basics 2017, Interactive Intelligence, Inc.


Caller ID is passed along as information in the event. The initiator can retrieve this information,
EXAMPLE
assign it as the value of a variable, and then use that value in the handler.
The best way to understand how these three settings work together is to use an example. For
EXAMPLE
this example, our initiator is called Dog Barking. Notice the difference among the following four
example scenarios:

Notification Object Type Dog

Object ID {all}

Event Bark

With these initiator settings, the handler would start any time any dog barked.

Notification Object Type Dog

Object ID Fido

Event Bark

With these initiator settings, the handler would start any time a dog named Fido barked.

Notification Object Type Dog

Object ID Fido

Event {all}

With these initiator settings, the handler would start any time a dog named Fido did anything.

Notification Object Type Dog

Object ID {all}

Event {all}

With these initiator settings, the handler would start any time any dog did anything.

In a situation where an event matches two primary handler initiators, the handler with the initiator
FOR YOUR
INFORMATION
which most closely matches the event will be ran. Unless both initiators are exactly the same, then
neither handler will run, and an error will be written to the event log.

2-13Handler Basics 2017, Interactive Intelligence, Inc.


EVENT INITIATOR OUTPUTS

Initiators can pass information (attributes of the object) to a handler. The information initiators pass
into handlers is specified on the initiators Outputs page.
The Incoming Call initiator passes into its handler the Call Identifier, the Line Identifier, the number
EXAMPLE
the caller dialed, and other information. A handlers uses this information to perform actions on the
incoming call object.

CLASSIFICATIONS OF HANDLERS
We have already learned that handlers can be classified according to their initiator as:
Event Initiated
Subroutines

Handlers are also classified according to their functions. All handlers are stored in the same
directory by default. They have the same .ihd extension and appear to be identical. The only thing
that visibly distinguishes the various types of handlers from each other is their naming convention.
Primary handlers are handlers which may act directly on objects in the system. Only one primary
handler can be activated for a given initiator, to prevent two or more handlers from performing
conflicting actions on a single object.
Monitor handlers have the word monitor somewhere in their file name.
Customization point handlers are subroutine handlers which are distinguished by the word
custom in their file name.

2-14Handler Basics 2017, Interactive Intelligence, Inc.


EVENT INITIATED HANDLERS
Each handler has an initiator that watches for an event of a unique type to occur on a unique object.
When an event is generated, Interaction Processor starts any handler whose initiator is configured
to start when that event occurs, like an incoming call or a user lifting the telephone handset. Event
initiated handlers consist of two types primary and monitor handlers.
Primary Handlers These handlers generally act directly on objects, such as calls, within the system.
Only one primary handler can be activated for a given initiator. For example, you cannot activate two
primary handlers that both start with the Incoming Call initiator. Only one handler can act on the
incoming call. This restriction prevents two handlers from performing disparate actions on a single
object. If you attempt to activate two handlers that start with the same initiator, IC will generate an
error message in the Event Log. Only the first handler published will be activated and then respond to
the event. A primary handler can be an event- initiated or subroutine-initiated handler.
Monitor Handlers Monitor handlers objectively monitor specific interactions in the IC system.
Monitor handlers do not actively manipulate or modify objects in the system. Since monitor
handlers are not acting on objects, more than one monitor handler can use the same initiator. The
OnHoldAudioRandomizationMonitor handler is a good example of a monitor handler, initiated by the
CallHeld event.

SUBROUTINE HANDLERS
Subroutines Subroutines are handlers that are called (or initiated) by other handlers. Subroutines
are used often in IC to make existing handlers more manageable. There are also special subroutines
that are designed to allow handler developers to customize the system. These special subroutines are
called customization points.
Customization Points Many handlers contain customization points. Customization points are
handlers in which you can implement customized logic and not worry about future IC releases
overwriting your custom logic. Customization points are just subroutines. These customization
subroutine calls will always be in the same location, so you can easily preserve your custom logic.
Interactive Intelligence will not overwrite these handlers during service update or upgrade installs.
Your logic or customized code will not be disturbed.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following lab in your lab manual:
Lab 4: Triggering Handlers

2-15Handler Basics 2017, Interactive Intelligence, Inc.


2.3 Building Handlers

BUILDING HANDLERS

The process for building handlers is the following:


1. Create a handler or open an existing handler.
2. Add steps.
3. Define step parameters.
4. Connect steps.
5. Save the handler.
6. Publish the handler.
7. Activate the handler.
8. Test the handler.

CREATING A NEW HANDLER


When you first start Interaction Designer, the new handler window is displayed. If you have no
new handler window open, then from the File menu click New. This action opens a new, blank
handler window.
Each IC release comes with an extensive library of functional handlers. You will probably not need to
create new handlers often. Listed below are some reasons to create a handler:
Creating a base handler Because the functionality of the existing base handlers is so extensive,
new base handlers are not often needed. However, if you have a unique environment you may need
to add a handler in addition to the base handlers released with the product. You will need to choose
from the unused event initiators, or use the Custom Notification initiator.
Creating a subroutine New subroutines are more common than new base handlers. The base
handlers perform most functions that companies need. Some customers modify the way a base
handler acts by using subroutines. Subroutines can be called either from a handler or from
Interaction Attendant.

2-16Handler Basics 2017, Interactive Intelligence, Inc.


CUSTOMIZATION POINTS

The only supported modifications to base handlers are through customization points. To modify a
handler, open the handler and find the appropriate customization point. Now open the subroutine
handler that the customization point calls by right-clicking on the customization point and selecting
Download Subroutine From Server. This action will allow you to browse to a location in which to
save the most recent version of the downloaded customization handler. Now you can add the steps
for the new logic that you require.
Interactive Intelligence STRONGLY recommends against modifying base system handlers that ship
CRITICAL
with our products. Use the customization points as much as possible. Submit request for new handlers
to ideas.inin.com. Using the customization points is a best practice for a maintainable system from SU
to SU and version to version. Modifying base handlers introduces risk when applying updates and will
require migration effort to maintain your customizations with each update.
If you choose to modify any of the base handlers, it is at your own risk. When Support determines
that an incident is due to modification of a base handler, they will close the case. Also, since the
Service Update process is automated, a customized base handler may be overwritten any time an
SU is applied, and your custom functionality will be gone until you merge your changes back into the
new base handlers supplied in the SU.

TOOLS AND STEPS

2-17Handler Basics 2017, Interactive Intelligence, Inc.


Tool Each tool has the ability to perform a specific action in a handler. For example, the Assignment
tool creates a variable and assigns a value to that variable. When a tool is dragged from the design
palette into a handler or subroutine, it becomes a step in that handler. As you link these steps, you
create and order the series of actions that become the functionality of the handler.
Step A step is a single instance of a tool dragged from the design palette into the handler window.
Steps appear as named boxes in the handler and are connected to other steps by links. Steps are
similar to functions in a program. Each step in a handler represents a single action that the handler
performs when it runs. For example, an Assignment step can assign a value to a variable. A Whitepages
step can look up a telephone number in the Interaction Center Whitepages. A Condition step can
evaluate a condition and decide what step comes next. A Log Message step can write information to a
log. Each step performs an action in the handler. Combinations of linked steps make up the logic of the
handler that responds to an event that has occurred on the Interaction Center server.

PARTS OF A STEP

Icon The unique icon that corresponds with the step type. For example, all Generate HTML steps
have the same icon as the Generate HTML tool. You cannot change a steps icon.
Step Type The type of tool from which the step was created. For example, if the step was created
from the Assignment tool, the step type is Assignment.
Step Label The custom name a handler author has given this step. Use these labels as quick
reminders of a steps purpose in a handler. If you do not enter a name for a step, the step label is the
same name as the step type. Assignment and Condition steps can be auto labeled. With auto labeling
the current assignment or condition is set as the label.
Exit Paths The paths a step can take as a result of a steps action. It is through these exits that steps
link to other steps. For example, a Condition step has two exit paths: True and False. If the condition
evaluated by the Condition step is true, the step will exit along the true path. If the condition
evaluated by the Condition step is false, the step will exit along the false path.
If a step has no exit paths, or no links from an exit path, the handler or subroutine ends after the
FOR YOUR
INFORMATION
completion of that step.
Step Numbers Each step also has a number. This number is the order in which the step was created
in this handler and will never change. The step number does not indicate the order in which the steps
should be placed. The steps should be placed in a logical order so that the handler functions properly.
If you delete a step, the number is not deleted. Any additional steps will begin numbering with the
next value after the value of last step added.

2-18Handler Basics 2017, Interactive Intelligence, Inc.


WORKING WITH STEPS
There are a number of actions that you can perform on steps in Interaction Designer. These
actions include:
Adding new steps To add a step to a handler, drag and drop the required tool onto the handler. You
can also double-click the tool in the Design Palette. Performing either action will place the step in the
upper-left corner of the active window. From there, it can be dragged to the necessary location within
the handler.
Selecting steps To select a step, just click it. Selected step are surrounded by a dark blue halo.
Select steps to move, delete, copy, or delete steps.
Selecting multiple steps To select multiple steps, click a blank spot in the handler window and drag
the selection box around over the required steps. All of the steps within the selection box will be
selected. You can move, copy, or delete multiple steps in this way.
Deleting, copying, and pasting steps These actions work just like standard Windows delete, copy,
and paste operations. Select the step or steps and use the Edit Menu or standard toolbar to select
the appropriate action. When you paste a step into a handler, it will be placed in the upper-left hand
corner of the current handler window. You can also delete, copy, and paste steps between handlers.
Moving steps To move a step or steps, select the step(s) then click and drag it to the correct
location. If you drag the step off the current handler window, it will scroll until you release the step.
Deleting steps To delete a step or steps, just select the step(s) and press the Delete key. You will be
prompted to verify the deletion.

CONNECTING PATHS

Entry Paths These are the paths taken by objects entering a step. They are shown in red when the
step is selected. A step can have multiple entry connections.
Exit Paths These are the paths taken by objects exiting a step. They are shown in green when the
step is selected. Each exit path can only have one connection.
Connection Lines Connection lines connect the steps together. They are black unless connected to
a step that is selected. They will remain connected if you move the step.
Modifying Connecting Paths You can modify the links between tool steps by clicking and dragging
on a wire in the link. Once a wire has been moved and placed in this fashion that wire will remain fixed
regardless of how the two connected tools are moved. The first and last sections of a link cannot be
fixed in this manner. If you want to add more wires to a link, right-click on the wire and select Add
Anchor.

2-19Handler Basics 2017, Interactive Intelligence, Inc.


Show Whole Path On large handlers, it can be difficult to see both the source and destination node
for a link. You can right-click on a link between two steps and select the Show Whole Path menu item.
Interaction Designer will resize the handler view to include both the source and destination nodes.

CONNECTING STEPS

To connect two steps:


1. Left-click the exit path of the originating step.
2. Drag to the destination step.
3. Release the mouse button.

STEP PROPERTIES

The Properties notebook is a collection of tabbed pages that make up a step. It is on these pages that
you customize the properties of the action that the step will perform. You can view the properties of
the step by double-clicking the step, or right-clicking the step and selecting Properties from the menu.
Each step may have one or more of the following pages:
General page
Statement or Settings page
Inputs page
Outputs page
2-20Handler Basics 2017, Interactive Intelligence, Inc.
GENERAL PAGE
Every step has a General page. In this page, you enter the step label and any notes about the step.

This page is often ignored by novice programmers but is very important. When you are building
a handler, the purpose of each step is well known to you. However, several handlers later or after
months have passed this information will not seem so clear. The passage of time is why it is so
important to document the purpose of each step at the time that the handler is written.
Use the label area to give the step a descriptive name that will allow you, or any other handler
developer, to quickly locate the step.
Use the notes area so that you, or any other handler developer, can determine the purpose of the
step and any other useful information concerning the step.

STATEMENT OF SETTINGS PAGE


This page lists all the parameters needed by the step to perform the required action.

Some of these parameters are be optional. A Statement or Settings page is usually present if the
step has no input or output parameters.
2-21Handler Basics 2017, Interactive Intelligence, Inc.
INPUTS PAGE
This page lists all the parameters needed by the step to perform the action. If a step has an Inputs
page, at least some of the parameters have usually been defined in a previous step. Some of these
parameters are optional.

OUTPUTS PAGE
This page displays the values that are created as a result of the step performing some action. Since
these output values are stored in variables, they can be accessed by other steps in the handler.

For a description of the properties and pages of each step, see the Tools section of the Help. You can
FOR YOUR
INFORMATION
also click the Help button inside a steps Properties notebook for help on that tool.

2-22Handler Basics 2017, Interactive Intelligence, Inc.


SAVING HANDLERS

Whenever a handler contains unsaved changes, Interaction Designer will indicate there are unsaved
changes by placing an asterisk (*) beside the handler name in the title bar.

Saving a handler in Interaction Designer is no different from saving a file in any other Windows-
based program. From the File menu, just select Save or click the save button.
You cannot save a handler and then save another handler with the same name to the same location.
FOR YOUR
INFORMATION
It will overwrite the existing handler. To save a handler with the same name as an existing handler, it
must be saved to a different location.

THE PUBLISHING PROCESS


A handler is not available to run on an IC server until it has been published on that server. When you
publish a handler in Interaction Designer, the following events occur:
Interaction Designer compiles the handler into a .class file that Interaction Processor knows
how to run.
Before the handler is compiled, you are prompted for a description of the handler and also asked
to set the activation state for the handler. If you are publishing a subroutine handler, you will also
be required to enter a subroutine category in a combo box. The subroutine category determines
under which tab the handler will appear in the Subroutines page of the Design Palette.
The Interaction Designer bundles up the source (.ihd) file and the compiled (.class) file and hands
them off to AdminServer which actually performs the publish operation by saving the .ihd and

2-23Handler Basics 2017, Interactive Intelligence, Inc.


.class files on the server and then sending out a notification to Interaction Processor that the
handler was published.
The initiator in a handler is configured for a specific event (for example, StationOffHook) to
occur to a specific object (for example, any station). During the publish process, Interaction
Processor informs Notifier that when the specified event occurs to the specified object, Notifier
must let Interaction Processor know. Afterward, when Notifier tells Interaction Processor that
the event has occurred, Interaction Processor starts an instance of that handler.
After a subroutine is published, it can be selected from the subroutine palette and placed in a
FOR YOUR
INFORMATION
handler. However, unless it is also active, it will not execute.
One of the great things about handlers and the Interaction Designer is that there are few compiler
errors. Since the code is generated automatically, you rarely have the chance to type in bad code.
However, although Interaction Designer and the publish utility can shield you from making many of
the syntax errors inherent in programming, they do not protect you against bad logic. For example,
Interaction Designer and the publish utility will not generate an error if you create an infinite loop in
a handler. Bad logic will become clearer as you begin designing handlers.
Handlers must be published on a computer connected to the Interaction Center server on which the
FOR YOUR
INFORMATION
handlers will run.
It is important to make back-up copies of current handlers and subroutines before publishing new
CAUTION
versions. Back-up copies are especially important if you are overwriting existing handlers and
subroutines with modified handlers of the same name. A handler will be overwritten if a new or
modified handler is saved to its directory under the same name.

PUBLISHING A HANDLER
1. From the File menu, choose Publish or click the Publish button on the toolbar.
2. Type a description of your handler in the Publish Handler dialog box that appears. If you want
the handler to be active upon being published, select the Activate Handler check box and select
whether the handler is a Primary or Monitor handler.

2-24Handler Basics 2017, Interactive Intelligence, Inc.


3. If you are publishing a subroutine handler, type a new subroutine category or select an existing
subroutine category. These categories represent tabs on the subroutine page of the design
palette. Typing a new category name creates a tab in the subroutine page.

4. Click OK in the Publish Handler dialog box to continue the publish process.

INTERMEDIATE PUBLISH
It is possible to design and build your handlers on a development IC server, perform an intermediate
publish, then load them onto the production server to complete the publishing process.
Generating an .i3pub file is a means of breaking the publishing process into two stages so that a
handler can be assembled, packaged into an intermediate format and saved to disk, then transferred
and published on an entirely different server.
This intermediate file contains the .class file, the configuration data for DirectoryServices, the audio
prompt data, and a copy of the .ihd file, along with everything else needed for the publish.
A separate executable is released with Interaction Center called EICPublisherA.exe that allows
users to install the i3pub files without the need for Interaction Designer.
EICPublisherA is a simple command-line utility that can read .i3pub files and finish publishing
them to the current IC server. In addition to publishing, EICPublisherA will also activate the handler
if selected by the Interaction Designer user who created the intermediate file. Users can right-click
on a *.i3pub file, choose Open With, browse to \I3\IC\Server and choose EICPublisherU.exe as
the associated application, allowing a .i3pub file to be published just by double-clicking it.

IMPORTANT NOTES ABOUT PUBLISHING


Backup Copies Every time you publish a handler, a copy of the handler (.IHD file) is saved in
the same directory as the .class file - \I3\IC\Server\Handlers. To recover this file, first copy it
to another location, then open the file using Interaction Designer. Only the last published copy

2-25Handler Basics 2017, Interactive Intelligence, Inc.


is saved in the \Server\Handlers folder. Any previously saved copies are overwritten during
the publishing process. If you want to save older copies of handlers, save them manually to a
backup directory.
Publishing Rights Any user who will be designing and maintaining handlers must have the User
Rights to Publish Handlers and Manage Handlers, which are assigned in Interaction Administrator.
Otherwise, the Publish button will not be selectable.
Errors If there are code errors in the handler, a message describing the error and its location will
appear in the message palette. You will not be able to publish the handler until all errors are resolved.
Warnings A handler can receive Warning messages in design mode. You will still be able to publish
the handler, but there can be other tasks for you to perform after you have published you handler.
It may be that a change you made in your current handler has potentially affected the logic of a
dependent handler.

PUBLISHING INDICATORS
The state of a handler is indicated by a face icon on the Palette toolbar and on the Handler Messages
tab of the Messages Palette.

Icon Meaning

The green smiling face indicates a publishable handler without


any errors in the message log.

The yellow face indicates that the handler is in a publishable


state, but that the message log contains warnings (for example
the handler contains a call to a subroutine that has not been
published on this server).

The Red face indicates that the handler is not in a state that
will allow it to be published (for example, contains steps with
required fields not yet assigned values).

A green smiling face does not necessarily mean that the handler will function as intended, merely
FOR YOUR
INFORMATION
that all required fields have been assigned values and the handler is in a state that can be published.
Messages Palette The Messages palette provides information about why a handler is not able to
be published. If a condition exists that would stop a handler from being published, it will be displayed
in the Messages palette.

ACTIVATE (OR MANAGE)


A handler will not be used on an Interaction Center server unless it is active, or managed.
Managed handlers are published handlers that run on your Interaction Center server.
Unmanaged handlers are published handlers that do not currently run on your Interaction
Center server.

When a handler or subroutine is first published, you can make it active immediately. If you choose
not to activate the handler, or if the handler has been imported from another server, or previously
been made inactive, you will need to activate it in the Manage Handlers notebook before it can be
used in Interaction Center. Manage Handlers is available under the Utilities menu or in the Server
Configuration in Interaction Administrator. You must have the User Right to Manage Handlers
given in Interaction Administrator to perform this task.

2-26Handler Basics 2017, Interactive Intelligence, Inc.


ACTIVATION PROCESS

As we have discussed, once a handler has been built it must go through a three-step activation
process. The handler must be:
Saved
Published
Activated

There is a slight difference between publishing a handler which is not yet active and publishing one
which is already active.
A New Handler:
Saving creates the handler as an .ihd file in a location that you specify.
Publishing compiles the handler into a proprietary format and stores it as a .class file.
Activating a handler registers it with the Interaction Processor and puts the handler into
effect immediately.
A handler can be activated during publishing.

An Existing Active Handler:


Saving overwrites the existing .ihd file that resides on your hard drive.
Publishing overwrites the existing .class file. If the handler is already active, the box will be
selected to make it active immediately. Now, you can clear the box to deactivate the handler at
the completion of publishing.

2-27Handler Basics 2017, Interactive Intelligence, Inc.


ACTIVATING A HANDLER FROM INTERACTION DESIGNER

This procedure can be performed only after you have published your handler(s).
1. On the Interaction Designer menu bar, choose Utilities... Manage Handlers.
2. On the Primary Handlers page, select the handler(s) in the Inactive Handlers list.
If you do not see the handler listed in the Inactive Handlers list, check the Active Handlers list to
FOR YOUR
INFORMATION
see if the handler is already activated. If so, you do not need to activate the handler and can quit
this procedure now. It may also be that the handler is running as a Monitor Handler.
3. Click the Add button to move the selected handler to the Active Handler list. When you click
OK, the handler is activated and is available for use on the Interaction Center server. You can
now debug the handler.

UNMANAGING A HANDLER FROM INTERACTION DESIGNER


Perform this procedure if you want to stop a handler from running on the Interaction Center Server.
On Interaction Designer menu bar, choose Utilities... Manage Handlers.
1. On the Primary Handlers page, select the handler(s) in the Active Handlers list.
If you do not see the handler listed in the Active Handlers list, check the Inactive Handlers list to see
FOR YOUR
INFORMATION if the handler is already deactivated. If so, you do not need to deactivate the handler and can quit
this procedure now. It may also be that the handler is running as a Monitor Handler.
2. Click the Remove button to move the selected handler to the Inactive Handlers list. When you click
OK, the handler is deactivated and is no longer available for use on the Interaction Center server.
If you deactivate a subroutine and that subroutine is called by a currently running (activated)
CAUTION
handler or subroutine, the calling handler will run but it will not function as expected since it calls a
subroutine which is no longer activated.

2-28Handler Basics 2017, Interactive Intelligence, Inc.


TESTING HANDLERS
ALL modified handlers must be thoroughly tested on a test system before introducing them into
CRITICAL
a production environment. Malfunctioning handlers can produce severe errors on a production
system. A poorly designed handler can consume excessive amounts of resources or even interrupt
the core business function of a company. It is imperative that this step is implemented to ensure that
the phone system (IC) is not negatively impacted.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following labs in your lab manual:
Lab 5: Managing Handlers
Lab 6: Intermediate Publish

2-29Handler Basics 2017, Interactive Intelligence, Inc.


2.4 Working with Basic Tools

BASIC TOOLS
The Basic tools are versatile tools that provide common programming functionality to the handlers.
They are used to create variables, assign values to variables, and evaluate the values of variables.
Although you will find more tools under the Basic tab in Interaction Designer, we cover only these
four tools in this section:
Assignment
Condition
Selection
Notify Debugger

Each step has a basic function and performs some of the most common tasks in all handlers. These
Basic steps are the building blocks of handler creation. The following pages discuss each step in
more detail.

ASSIGNMENT TOOL

This tool declares a variable and assigns a value to that new variable or to an existing variable.
The assigned value can be the value of another variable, a literal value, or a complex expression
constructed with the Expression Editor Assistant. Once you declare a variable, it is available to all
steps throughout the handler.
For example, an assignment step might copy the value John to the contents of the variable named
sFirstName.

2-30Handler Basics 2017, Interactive Intelligence, Inc.


Statement Page From the Statement page you can declare a new variable and assign it a value, or
select an existing variable and assign a value to it.
Variable The name of the variable that you are creating or assigning a value. You can select new
from the drop-down list to declare a new variable. The variables that appear in this list are variables
that have already been declared in this handler or subroutine.
Value This can be a literal value for the variable, a variable name, or an expression. You can only
assign values that are legal for the data type of the variable selected in the previous step. For
example, if the variable type is String, then the value must be a string expression (an expression
combining one or more existing string variables), a variable, or a literal value.
Exit Paths:
Next This step always exits along the Next exit path.

CONDITION

This tool tests a conditional expression and follows the link associated with the result of that test.
A conditional expression resolves to a Boolean value (either True or False). Therefore, a conditional
step has a True exit path and a False exit path.
A conditional step might compare a variable sFirstName to a string value John. If the value of
EXAMPLE
sFirstName contains the string John, then the handler continues execution on the True branch of
the conditional step. However, if sFirstName does not contain the string John, then the handler
continues on the False branch.

2-31Handler Basics 2017, Interactive Intelligence, Inc.


Statement Page On the Statement page, you can view an existing conditional expression or create
an expression either by typing it in directly or by using the Expression Editor Assistant.
Current Condition This parameter contains the conditional expression. You can type a new
condition or build a complex expression using the Expression Editor Assistant. Remember that the
expression you build must result in a Boolean value.
A single variable in the Current Condition parameter must always be a Boolean variable that has
been assigned a value somewhere else in the handler, or was created in the initiator step that
started the handler or subroutine.
It is important to keep track of the logic being used in setting up the conditional expression, especially
when it is the condition of a Boolean variable that is being checked. For example, consider a Boolean
variable bCallReceived that has the value of False. If the condition expression is written just to look
at the variable bCallReceived without an associated value given, then the handler will continue on
the False branch because the value of bCallReceived is False. Also, if the expression compares the
variable bCallReceived to the value False, then the handler will continue execution on the True
branch because it is true that the value is False.
Exit Paths:
True If the condition evaluated by this step has a value of true, this step takes the True exit path.
False If the condition evaluated by this step has a value of false, this step takes the False exit path.

SELECTION

This tool tests a list of condition statements. The tool begins testing with the first condition in the list,
then the second, and so on. Each condition in the list has a corresponding exit path. The first condition
that evaluates to true causes the handler to follow the exit path associated with that condition.

2-32Handler Basics 2017, Interactive Intelligence, Inc.


If the value of sFirstName is John, go to the step called Hello John. If the value of sFirstName is
EXAMPLE
Jane, then go to the step called Hello Jane.
If no conditions evaluate to True, the Default exit path is taken.

Statements Page On the Statements page you can add, edit, delete, or change the order of the
conditions. The conditions in the list are evaluated in the order they are listed. The first true
conditions exit path will be followed.
Condition list This is a list of any conditions you have built using the Add or Edit button. There is an
exit path for every condition in this step.
Add button Click this button to create a condition in the Condition list. You can use the Expression
Editor Assistant to build the condition expression. Adding a condition will also add an exit path that
corresponds to that condition.
Edit button Click this button to edit the selected condition in the Condition list.
Delete button Click this button to delete the selected condition from the Condition list. Deleting a
condition will also delete its corresponding exit path.
Move Up button Click this button to move the selected condition higher in the Condition list.
Move Down button Click this button to move the selected condition lower in the Condition list.
Exit Paths The exit paths for this tool are the conditions in the Condition list. An exit path will
appear for each condition. A default exit path is always present and is taken if no conditions evaluate
to true.

NOTIFY DEBUGGER

2-33Handler Basics 2017, Interactive Intelligence, Inc.


This tool creates a breakpoint in a handler you are debugging. If there are no Notify Debugger steps
in a handler, the initiator will be set as the first breakpoint. In debug mode, a handler will pause
execution at the Notify Debugger step. If there is at least one Notify Debugger step in a handler, you
will be prompted when you start a debug session to select the initiator or a Notify Debugger step to
use as the first breakpoint.

Settings Page:
Label Enter the unique label for this debug session. This is a required field. If you add another
Notify Debugger step to this handler, it must have different name.
Exit Path:
Next This step always exits along the Next exit path.

OTHER BASIC TOOLS


These tools will be covered in more depth in other sections of the material.
Write Trace Message Writes a message to the ip.ininlog file along with the handler name, time
stamp, threadID, and step ID.
Table lookup Retrieves data from an IC table created in Interaction Administrator.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following labs in your lab manual:
Lab 7: Programming Logic: Variables
Lab 8: Programming Logic: Condition and Selection
Lab 9: Working with Basic Tools

2-34Handler Basics 2017, Interactive Intelligence, Inc.


2.5 Debugging Handlers

DEBUGGING HANDLERS

Debugging allows you to monitor a handler as it runs and to pause it at locations or situations of your
choosing by setting breakpoints. When the handler runs on the server, it pauses when it reaches the
selected initial breakpoint, either the initiator or a Notify Debugger step. You can then establish other
breakpoints in the handler and let the handler execute until it reaches the next breakpoint.
By setting a breakpoint on a particular step, you can allow the handler to execute normally until
it reaches that step, at which point execution will pause.
By setting a breakpoint on a change in a variable, you can have the debugger pause execution
(break) whenever the handler changes the variables value.

When debugging a handler, you are viewing the handler in read-only mode. You can view step
properties by double-clicking the step.
When a subroutine step is encountered you can step into the subroutine to debug it, by clicking
the Step Into button on the toolbar.

INTERACTION DESIGNER MODES


Interaction Designer can operate in one of two modes:
Normal Mode
Debug Mode

Normal Mode is used for designing and working with handlers, while Debug Mode is used for
debugging and dissecting handlers. Each mode is described more completely on the following pages.

2-35Handler Basics 2017, Interactive Intelligence, Inc.


NORMAL MODE
This is the mode that lets you edit, create, modify, or otherwise work with handlers.

In Normal Mode:
You can edit steps.
The Normal Mode icon appears in the Title Bar.
In the title bar, the file name is followed by .ihd.
The Debug toolbar is not visible.
The Debug palette is not displayed.
The wallpaper is white and may have the grid display if you have the option selected.

2-36Handler Basics 2017, Interactive Intelligence, Inc.


DEBUG MODE
Debug mode allows you to step through the handler and monitor the values of variables as the
handler executes.

The Interaction Designers Debug mode is closely integrated with Interaction Processor to support
debugging over a network. This integration allows you to run Interaction Designer on a client
workstation to debug a handler even though that handler is actually executing on the server.
In Debug Mode:
You cannot edit steps.
The Debug Mode icon appears in the Title Bar.
The Debug watermark appears in the handler.
The Debug toolbar is displayed.
The Debug Palette is displayed.
You can set execution to a prior step.
You can change the value of variables under the Watch Variables, Step Variables, or Handler
Variables tabs of the Debug Palette.

PREREQUISITES FOR DEBUGGING


Before you begin the debugging process:
You must be running a copy of Interaction Designer connected to the server running the handler
you want to debug.
The handler you want to debug must be published and running (activated) on the server.

2-37Handler Basics 2017, Interactive Intelligence, Inc.


DEBUG TOOLBAR
In Debug mode, the debug toolbar is displayed.

Stop Session Stops the debug session. A prompt gives you the choice to allow the handler to
complete its execution or to terminate it at the current step.
Run Advances to the next breakpoint or the end of the handler if there are no more
breakpoints.
Step Allows you to advance through the handler one step at a time.
Step Into Subroutine Opens up the subroutine associated with the current subroutine step, in
debug mode. This option is only selectable if the current step is a subroutine step.
Step Out of Handler Used to step out of the current handler. If the current handler is a
subroutine, the debug session returns to the calling handler. Otherwise, the debug session stops
and the handler executes to the end.
Show Step Being Executed in Current Handler Brings focus to the step currently being executed.
Add Handler to Debug Session Opens the Add Handler(s) to Debug Session dialog which
allows you to select one or more handlers to debug.
Restart Debug Session Used to start a new debugging session for the handler.

DEBUG PROCESS
Use one of the following methods to place a handler into debug mode:
From the Utilities menu, choose Debug Handlers.
Select the handler(s) that you want to debug and press OK. You can select multiple handlers
using shift-click or control-click.

OR
Open the handler(s) that you want to debug.
Publish the handler(s) if you have made changes to it.
From the File menu, choose Debug Immediate or click the Debug tool on the Standard Toolbar.

THEN
Invoke the event that starts the handler. This event is defined by the handlers initiator.
Move through the steps of the handler using the Debug tools.
Use the Debug palette to monitor variable values.

2-38Handler Basics 2017, Interactive Intelligence, Inc.


You can only debug one specific instance of a handler at a time. Once a handler in debug mode
FOR YOUR
INFORMATION
reaches the end of its execution, you can click Restart Debug Session, on the debug toolbar, to run
the handler in debug mode again. This debug session then waits for the next instance of the handler
to run.

OPENING A HANDLER IN DEBUG MODE

1. From the Utilities menu, choose Debug. The Debug Handler(s) dialog box appears.
2. Select the handler you want to debug from the list of handlers.

You can select multiple handlers to place in Debug Mode using Ctrl-click and Shift-click.
FOR YOUR
INFORMATION

If the handler contains at least one Notify Debugger step, you will be prompted to select the
initial breakpoint.
A read-only copy of the handler appears in Interaction Designer. Active breakpoint steps appear
in red.
When the handler is started on the Interaction Center server, the initial breakpoint in the handler
becomes highlighted and the handler execution pauses. The handler is now running in debug mode.
While in debug mode, you can check the values of variables and determine which step is changing
the value of a variable.

SETTING A BREAKPOINT
A breakpoint causes a handler running in debug mode to pause execution. While the handler is
paused, you can check the values of variables. There are two ways to create breakpoints in handlers.
Publish a handler with Notify Debugger steps.
Create a breakpoint on a step after the handler is in debug mode.

2-39Handler Basics 2017, Interactive Intelligence, Inc.


To create a breakpoint on a step, the handler must be running in debug mode. Then:
1. Right-click on the step you want to set as a breakpoint.
2. Choose Set Breakpoint from the menu that appears. The step color changes to red. When the
debug handler runs, it will automatically pause at this step.

If a handler does not have a Notify Debugger step in it, the Initiator will serve as a breakpoint when
FOR YOUR
INFORMATION
debug mode is started.

DEBUG PALETTE WATCH VARIABLES

When you run a handler in debug mode, the Debug Palette is automatically opened. The Debug
Palette contains four tabs for viewing the activity of a handler during a debug session - Watch
Variables, Step Variables, Handler Variables, and Call Stack.
The Watch Variables page is used to select specific variables that you are interested in monitoring
during the debug session. To add a variable to the Watch Variables page:
Right-click in the page and select Add Watch from the menu.
Double-click Break On Value Change if you want to create a breakpoint when the variable
value changes.
Click any underlined value to change the variable value while debugging.

Values displayed in red have been changed by the current step. If a variable is of a List type, you can
FOR YOUR
INFORMATION
see all of the values in the list by clicking the plus sign (+) to expand it.

2-40Handler Basics 2017, Interactive Intelligence, Inc.


DEBUG PALETTE STEP VARIABLES

The Step Variables page is used to view variables used by a particular step in a handler running
in debug mode. As you step through the handler or advance to the next breakpoint this page will
display all variables used by the currently selected step. You can step through the handler keeping
the Step Variables page open to view variables and their values for every step. You can click any
underlined value to change that value manually for the debug session.
Values displayed in red have been changed by the current step. If a variable is of a List type, you can
FOR YOUR
INFORMATION
see all of the values in the list by clicking the plus sign (+) to expand it.

DEBUG PALETTE HANDLER VARIABLES

The Handler Variables page is used to view all of the variables that are defined for a handler running in
debug mode. You can click any underlined value to change that value manually for the debug session.
Values displayed in red have been changed by the current step. If a variable is of a List type, you can
FOR YOUR
INFORMATION
see all the values in the list by clicking the plus sign (+) to expand it.

DEBUG PALETTE CALL STACK


The Call Stack is used to view the processes that led to the currently executing handler.
A handler will appear in the call stack when it is running in debug mode. The currently executing
handler will have an asterisk (*) beside the level number. The currently executing step will have a
solid line around it.

2-41Handler Basics 2017, Interactive Intelligence, Inc.


The columns are:
Level This indicates from where this handler was started. In the example above, System_
StationOffHook is the initial handler (Level 0). It contained a subroutine call to PlayTheMessage
(Level1) which called the InputSomeDigits (Level 2) subroutine.
Step ID The Step ID indicates the step number of the step that led to the next level in
the call stack. In this example, step 86 in System_StationOffHook is the subroutine step for
the PlayTheMessage subroutine. Step 4 in PlayTheMessage is the subroutine call to the
InputSomeDigits subroutine.
Handler Name This is the name of the .ihd file for the handler.

You can select entries in the page to view other handlers that are in the call stack. For example, in
the illustration above, if you double-click the 1 in the Level column, focus will be set to that handler.
The calling step is displayed with a dashed line around it.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following lab in your lab manual:
Lab 10: Debugging Handlers

2-42Handler Basics 2017, Interactive Intelligence, Inc.


2.6 Dependency Viewer

DEPENDENCY VIEWER
Track dependencies in handlers by using Dependency Viewer.

Interaction Designer supports the ability to track dependencies for the following objects used
in handlers:
DB Profiles
Global Variables
HTML Templates
Initiators
International String Resources
Prompt Resources
Sequence Resources
Subroutines
Tools

Choose the dependency that you want to view by selecting the appropriate item from the
Dependency: list box. Users can choose to group each type of dependency information in two
ways. You can either select to view the dependency information by what items (variables, tools, and
so on) are used by a handler or by handlers that use each item by clicking the appropriate Group
By radio button on the dialog.
One thing to remember is that the dependency information displayed in this dialog is for published
FOR YOUR
INFORMATION
handlers only. Actions performed on a handler that has not been published will not cause an update
in the dependency information.

2-43Handler Basics 2017, Interactive Intelligence, Inc.


For example, to change the subroutine CustomACDProcessEvent, first check to see what handlers
will be affected. To do so, follow these steps:
From the Utilities menu, select View Dependencies.
From the Dependency list box, select Subroutines In Handlers.
Select the Supporting Subroutine radio button.
Expand the Subroutine that you will be changing.

Other Options:
Export Dependency to XML Opens a Save As dialog to allow you to specify a file name and
folder in which to store the XML file.
Download Handler Opens a Browse for Folder dialog so that you can select a destination for
the selected handler when downloaded and opens that handler in Interaction Designer.
Debug Handler Opens the selected handler in debug mode.

The Dependency Viewer will allow you to place an inactive handler into debug mode, which can lead
CAUTION
to confusing behavior. Even though the handler looks like it is awaiting notification, it will not run.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following lab in your lab manual:
Lab 11: Using the Dependency Viewer

2-44Handler Basics 2017, Interactive Intelligence, Inc.


2.7 Working with Subroutines

SUBROUTINES

As we have already discussed, subroutines are handlers started by other handlers, as opposed to
handlers started by events on the Interaction Center server.
When an event initiated handler begins it is because an event in Interaction Center matches the
initiators properties. The handler executes step by step until it ends or encounters a subroutine call step.
Each subroutine that you create has its own unique subroutine call step.
When a handler executes a subroutine call step, it calls another handler that has a subroutine
initiator. Subroutines can only be started by a subroutine call from another handler. The subroutine
executes all of its steps. When the subroutine ends, control is returned to the subroutine call step of
the calling handler.
When the properties in Handler1s initiator are met, an instance of the handler begins. When it
EXAMPLE
reaches a subroutine call step the handler begins to execute the commands of Subroutine1. This
subroutine is like a detour. When all the steps are finished in the subroutine, the process is returned
to Handler1 to continue processing.

USING SUBROUTINES
Organizing Handler Logic Subroutines make handler building more visually manageable and
understandable. By localizing groups of steps into subroutines, you can cut down on the number of
steps that appear in the calling handler. Handlers with hundreds of steps can be difficult to understand
and manage; a few subroutines can make a large handler easier to modify and understand. Essentially,
by using subroutines properly, you break down the logic into bite-sized pieces.
Creating Logical Blocks of Code A subroutine can encapsulate a set of logic into a single callable
action. You can reuse a subroutine by calling it from any handler where that set of logic is appropriate.
Imagine that you have created a subroutine called LookupAccountNumber. Given a name, that
EXAMPLE
subroutine will open a customer database, look up the associated account number, and return
the account number to the handler that called it. Now, imagine a system of handlers that deals
with customer support. In such a system, the need to retrieve customer account numbers is
a common one. Thus, when you build the customer support system, you would be able to call
LookupAccountNumber from any handler that needs such information.
Easing the Maintenance Burden Recall the first example of LookupAccountNumber. Suppose that,
after your customer support handlers are finished and working, the customer database is redesigned.
Instead of directly tying customer name to account number the database has been changed to tie

2-45Handler Basics 2017, Interactive Intelligence, Inc.


customer name to social security number, and then in a separate table, to tie social security number
to account number. Since your LookupAccountNumber localizes the access to the database in a single
handler, you only need to change how LookupAccountNumber gets the information. Essentially, you
will change it to use the given name, retrieve a social security number, and then use the social security
number to retrieve the account number. This change can be made without any changes to all the
other handlers that call LookupAccountNumber.
Use subroutines where appropriate. If you are adding new functionality into an existing handler, add
FOR YOUR
INFORMATION
the functionality into a subroutine.

CREATING A SUBROUTINE

Creating subroutines is similar to creating handlers.


The primary difference is that every subroutine starts with a subroutine initiator. In the subroutine
initiator, you define the information that is passed into the subroutine from a handler that calls it. You
also define the information that will be passed back to the handler that calls the subroutine. These
pieces of information exchanged between a subroutine and its calling handler are called parameters.

2-46Handler Basics 2017, Interactive Intelligence, Inc.


PUBLISHING SUBROUTINE

When publishing a subroutine, select or enter a subroutine category on the Publish Handler dialog.
If you want to create a Subroutine category, type the name in the Subroutine Category box. This
action tells Interaction Designer to create a tab on the Subroutines Page of the Design Palette when
you publish the subroutine.
Subroutine categories are collections of subroutines. They appear together in the Subroutines Page
of the Design Palette. During the publish process, Interaction Designer creates a subroutine tool on
the Subroutines Page of the Design Palette in the category you specify.
When you publish HandlerClass_InputSomeDigits, the Publish Handler dialog box appears. When
EXAMPLE
you type in the new Subroutine Category, HandlerClass, a subroutine call is created under that
category on the Subroutines Page of the Design Palette.
Make the subroutine active either by checking the Activate Handler check box when you publish it
CRITICAL
or through the Utlities|Manage Handlers menu choice.

2-47Handler Basics 2017, Interactive Intelligence, Inc.


CALLING A SUBROUTINE

When a subroutine is published, a tool for that subroutine appears on the Subroutines Page of the
Design Palette. To create a call to the subroutine from any handler, just drag the subroutine tool
from the Subroutines Page of the Design Palette and drop it onto the handler.
To call the HandlerClass_InputSomeDigits subroutine, drag the subroutine call step from under the
EXAMPLE
HandlerClass Subroutines category into the handler, then connect it to the appropriate steps.
After adding the subroutine call into the handler, you may need to enter parameter information into
FOR YOUR
INFORMATION
the subroutine call step.

2-48Handler Basics 2017, Interactive Intelligence, Inc.


PASSING DATA BETWEEN HANDLERS
Subroutines typically perform some type of processing and return results to the calling handler. This
means that we have to have a way to pass information to the subroutine from the calling handler
and return information from the subroutine to the calling handler. To pass information among
handlers, it must be stored in variables. The values of variables are passed as parameters into a
subroutine or returned as parameters to the calling handler.
To pass variables in a parameter, you must define:
The parameter label
The variable label
The type of data that will be stored in the variable

Input Only is another parameter that may have to be defined. It defaults to Input Only = False.
FOR YOUR
INFORMATION

SUBROUTINE PARAMETERS
The subroutine initiator Properties dialog is used to define parameters that will be passed between
a subroutine and its calling handler or used as variables in the subroutine. When you publish any
subroutine, the parameters that you created on the parameters page will become parameters in a
subroutine tool that calls the subroutine. The subroutine tool will appear on the Subroutines Page
of the Design Palette.

The columns on the Parameters page are:


Label A label for the parameter. This label will appear in the properties notebook of the subroutine
call step which calls this subroutine.

2-49Handler Basics 2017, Interactive Intelligence, Inc.


If the Label and the Variable name are the same, it makes it much easier to track what value should
FOR YOUR
INFORMATION
be put in the subroutine call parameters.
Variable The name of the variable that holds the value being passed with this parameter.
Type The data type of this variable, such as integer or string.
Input Only Setting this parameter to true means that any change to the value of this variable will
not be passed back to the handler that called it. Setting this parameter to false means that a change
to the value of this variable will be passed back to the handler that called it. In other words, this
setting determines whether the calling handler is made aware of changes to variable values. This is
similar to the general programming concept of pass by value versus pass by reference. Pass by
value would correspond to setting Input Only=True in a handler, whereas pass by reference would
indicate Input Only=False.
The buttons on the Parameters page are:
Add button This button opens the Subroutine Parameter dialog used to create a variable.
Edit button This button opens the Subroutine Parameter dialog box used to edit a selected
variable.
Delete button This button deletes a selected subroutine parameter.
If you define a new variable in this process it becomes part of the subroutine.
FOR YOUR
INFORMATION

PASSING PARAMETERS

2-50Handler Basics 2017, Interactive Intelligence, Inc.


In this example, variable X is being passed as a parameter between handlers. X is defined in the
subroutine initiators as follows:

Notice the cleared check box. Because it is not checked, any change to the variable will be passed
back to the calling handler. The new value is used for any proceeding steps. In other words, the
variable is defined as an input/output variablea copy goes into the subroutine and comes back,
changing the original.
When the check box is checked, any changes to the variable are not sent back to the calling handler.
The calling handler will retain its value for the variable and use that for any subsequent steps. In
other words, the variable is defined as an input only variablea copy goes into the subroutine, but
does not come back.

IN CLASS EXERCISE
Using the previous diagram, find the value of X in Handler 1 given the following conditions:

Subroutine1 Subroutine2 Handler 1


Input Only Value Input Only Value Value of X After Subroutine Call

True True

True False

False True

False False

2-51Handler Basics 2017, Interactive Intelligence, Inc.


ADD A SUBROUTINE PARAMETER

To add a subroutine parameter:


1. Open the Subroutine Initiator and click the Parameters tab.
2. Click the Add button. The Subroutine Parameter dialog box appears.
3. Enter a parameter label. This label appears in the step that calls this subroutine.
4. Enter a variable name to hold the value entered for the parameter.
5. Choose a data type for the variable.
6. Do not check the This parameter will only be used as an input value to this subroutine check
box if you want the parameter to pass a value back to the handler that called it. Check it if you do
not want any changes to the parameter passed back to the calling handler.
7. If you want a default value for the parameter, select the appropriate radio button and then type
the constant or variable name in the text box. A default value can be a constant value, a variable,
or an empty string. The Input Only check box controls whether you can choose a variable for this
value, since the variable must be a variable in the calling handler to receive the return value. To
use this value, Input Only must therefore be False.
8. Click OK to add this subroutine parameter.

2-52Handler Basics 2017, Interactive Intelligence, Inc.


SUBROUTINE CALL PARAMETERS INPUTS

When a parameter is added to the Subroutine Initiator, it appears as a parameter on the Subroutine
Call step. There may be three pages on the Subroutine Call step: A standard properties sheet, an
input page, and an output page.
Inputs Page This page shows any of the parameters defined in the Subroutine Initiator as being
Input Only=True. This information means the value of the variable will be passed into the subroutine
but the value of the variable will not be returned to the calling handler. If there are no parameters
with this setting, there will be no Inputs page on the Subroutine Call step.

SUBROUTINE CALL PARAMETERS OUTPUTS

2-53Handler Basics 2017, Interactive Intelligence, Inc.


Outputs Page This page shows any of the parameters defined in the Subroutine Initiator as being
Input Only=False. This means the value will be passed into the subroutine, and the value will be
returned to the calling handler. If the value of the variable is changed in the subroutine, the changed
value is returned to the original handler. If there are no parameters with this setting, there will be no
Outputs page on the subroutine call step.

OBJECTS IN SUBROUTINES

To have an object move through a subroutine, you must make reference to it as a parameter in the
subroutine initiator. Otherwise, the object will not pass into the subroutine and you will not be able
to act on it in the subroutine.
Objects that are passed into a subroutine must be defined as any other variable in a handler.
Playing audio to a caller in a subroutine requires passing a Call ID variable with the following
EXAMPLE
information into that subroutine from a base handler:

Property Value

Label Interaction1

Type CallID

Variable Interaction1

Creating a variable for this object then passes it into the subroutine so the audio steps can interact
with the object.
If you did not configure the object being passed into a subroutine properly, the handler will not see
CAUTION
the object and therefore cannot act on that object.

2-54Handler Basics 2017, Interactive Intelligence, Inc.


Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following labs in your lab manual:
Lab 12: Working with Interaction1
Lab 13: Passing Parameters

2-55Handler Basics 2017, Interactive Intelligence, Inc.


2.8 Working with Expressions

EXPRESSIONS
Expressions are formulas that process literal values, variables, and operators to create a value.
You will find this type of processing useful in all but the simplest handlers, so understanding how
to create expressions will allow you to create flexible and powerful handlers. This topic offers the
information needed to begin building your own expressions.
You can create an expression for any input parameter that takes a normal value. You cannot create
FOR YOUR
INFORMATION
expressions for input parameters that take extended values, such as Call ID. You cannot create an
expression in an Output parameter. Output parameters can contain only variables.

EXPRESSION COMPONENTS
Literal Values Literal values are the simplest of expressions. For example, if an email Address input
parameter takes a string value, you can type joebob@aol.com. When the tool executes, the email is
sent to the specified address.
Remember that literal string values must be placed within quotation marks joebob@aol.com.
FOR YOUR
INFORMATION

One of the more useful features of literal values is that they can form part of a larger expression. For
example, you might have a Play Audio step that looks for the Do Not Disturb recording for a user.
Your expression might look something like this: StrUserName & _Do_Not_Disturb.wav.
This expression appends the string value contained in the variable StrUserName to the literal text
_Do_Not_Disturb.wav to form a unique file name when the tool executes.
Variables Variables are containers for values. Variables exist for both normal and extended types,
however you can declare variables only for normal types. Extended type variables are declared
automatically when you insert a step that processes an extended type value. There are multiple ways
to create a variable in a handler.
Explicitly declare one with the Assignment tool.
Implicitly create them when you drag a tool into a handler where that tool contains variable
names. For example, if you insert an Extended Place Call step into your handler, the variable
Digits is automatically declared in the handler.
Explicitly create one using the Variables Palette.
Create a variable within a Subroutine Initiator

Operators Operators are reserved words in expressions that act on literal values and variables. For
each normal data type, there is a set of operators that produce that data type. For example,
mathematical operators perform addition, subtraction, multiplication, and other operations on
integer and numeric values. String operators process strings, and so on.

EXPRESSION TYPES
Expressions have types depending on the result expected. Interaction Designer will not allow the
creation of an expression if the result does not match the type of the expression.
If an expression has a type of string, then the value can be Dog but not Dog or 4.
EXAMPLE

2-56Handler Basics 2017, Interactive Intelligence, Inc.


IN CLASS EXERCISE
Determine if these expressions match the expression type:

Expression Type Valid?

2+2 Integer

2+2 Integer

2+2=5 String

2+2=5 Boolean

EXPRESSION EDITOR ASSISTANT


Expression Editor Assistant is the Interaction Designer tool for building expressions. It is available
from any input that has a control to the right of it ( ).
The Expression Editor Assistant allows you to select from a menu of Expression options, even
though you can type an expression directly into a parameter box. The Expression Editor Assistant
makes expression building easier by helping you to build frameworks for complex expressions with
a few mouse clicks. Expression Editor Assistant also displays information about the expression that
you are building, including what type of value can go into each operand.
The Expression Editor Assistant helps you write expressions by checking for errors as you type. It
also assists by completing simple tasks for you. For example, if you type a quotation mark (to specify
a string value), it inserts the other quotation mark for you. This action ensures that your string
value is contained within quotation marks. In another example, if you begin to type an operator,
Expression Editor Assistant will recognize the operator, finish typing it, and insert ? symbols for
missing operands. This type of assistance and auto-correction can be a little unnerving, but it is
helpful when you become proficient at writing expressions. It also ensures correct syntax.

2-57Handler Basics 2017, Interactive Intelligence, Inc.


OPENING EXPRESSION EDITOR ASSISTANT

You can use the Expression Editor Assistant in any parameter that has the right-arrow button at the
end of it. When you click this button the Expression Editor Assistant appears.

PARTS OF THE EXPRESSION EDITOR ASSISTANT

Categories The box on the left contains a list of operator Categories to select from when building your
expression. For each normal value type, there are several operators that produce a value of that type.
Variables Any variables defined in this handler of the expected type will be listed here.
Literal values These operators work with literal values, such as for string types or 1 for
integer types.
Type Conversions These operators convert one type of data to another.
Mathematical operations These operators perform math operations.
Comparison operations These operators compare two values and return a Boolean value.
String operations These operators perform string operations.

2-58Handler Basics 2017, Interactive Intelligence, Inc.


Date/Time operations These operators perform DateTime operations.
List operations These operators perform list operations.
Constants

Symbols and Values This lists the available operators for each category based on the expression type.
Expression Type This is the type of expression expected.
Expression Editor Assistant limits your choice of operators to those that are legal for the input
parameter or selected operand. For example, if you are editing an input parameter that expects a
string, then only operators that result in strings are displayed in Expression Editor Assistant. This
rule also applies to operands. If you select an operand that expects an integer, Expression Editor
Assistant limits your operator choices to those that produce an integer.

TIPS FOR USING THE EXPRESSION EDITOR


You may find it easier to use the Expression Editor Assistant if you build the expression framework
first, and then populate that framework with data. For example, if you know that you are going to
have three individual elements within an expression, do this first:
1. Open the Expression Editor and select either the String Function or Comparison Operations to
build the Expression framework: ? & ? & ?
2. Working from left to right, select the first ? field.
3. Next, from the Categories side (left side) of the Editor, select the Variables category to choose
variables, Literal values category to type in a literal, or some other category.
4. Again, working from left to right, fill in the remaining elements by repeating Step 3 until the
expression is finished.
5. Click the control to close the Expression Editor Assistant.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following lab in your lab manual:
Lab 14: Building Expressions

2-59Handler Basics 2017, Interactive Intelligence, Inc.


Chapter

Default Handlers
3
Outbound Calls
Incoming Calls

www.inin.com/education 2017, Interactive Intelligence, Inc.


3.1 Outbound Calls

OUTBOUND CALL FLOW


The outbound call process begins in response to two actions:
Taking the phone off the hook and dialing
Dialing from the Interaction Desktop

1. When a call is made from a telephone handset, a Station Off Hook event triggers the System_
StationOffHook handler. This handler then generates an Outgoing Call Request event.
OR
When a call is made from the Interaction Desktop, an Outgoing Call Request event is
generated.
2. This event spawns an instance of the System_InitiateCallRequest handler. The main function of
this handler is to place an intercom call or a call on an outside line.
3. The System_InitiateCallRequest handler then passes the number dialed from Interaction
Desktop or handset into a subroutine called I3DialPlan.
4. I3DialPlan performs several important functions:
a. It gathers information about the phone number that was configured in the Phone Numbers
container in Interaction Administrator, such as Classification, Account Code information, Line
Groups, Display String, Dial String, and so on.
b. If there is no classification, I3DialPlan will determine if the call is internal, and if so, what user,
station or workgroup queue is being called. If I3DialPlan determines the call is external, it will
continue processing the call as such.
c. It determines if the call is coming from the system queue, a user queue, or a station queue.
d. If the call is from the system, I3DialPlan determines if the call is to an internal or external
number. If it is internal, the handler checks to see if it is to a user, station, or workgroup
queue and returns to System_InitiateCallRequest. If it is from the system queue and external,
I3DialPlan grabs the information that was configured in IA in the Phone Numbers container and
passes that information back to System_InitiateCallRequest.
e. If the call is from a valid station or user, then the classifications that are allowed for the
station or user. Classification settings are configured in Interaction Administrator. I3DialPlan
grabs the information that was configured in IA in the Phone Numbers container and passes
that information back to System_InitiateCallRequest.
f. Ultimately, I3DialPlan will return control to System_InitiateCallRequest, passing parameters
back to System_InitiateCallRequest which determines how to handle the call (e.g., Dial Plan
error, invalid security, external call, invalid extension, or internal call).

3-02Default Handlers 2017, Interactive Intelligence, Inc.


5. When the call object returns to the System_InitiateCallRequest handler, the handler checks
to see how to handle the call (I3DialPlan does the work and sends System_InitiateCallRequest
the answer). System_InitiateCallRequest performs this task through a Selection step. If the
call is invalid, a message will be played to the user, and a message is written to the call log
indicating why it is invalid (dial plan error or invalid security). The Interaction Desktop of the
caller will display an appropriate message in the Name column of the My Interactions window.
System_InitiateCallRequest ends.
6. If the call is an external call, it will either be placed and logged or System_InitiateCallRequest
will inform the caller of other issues, like busy signals, or lines not available, and log the
information. The Interaction Desktop of the caller will display an appropriate message in the
Name column of the My Interactions window. System_InitiateCallRequest ends.
7. If the number dialed is to an invalid extension, System_InitiateCallRequest passes the call to
InteractionAttendantEntryPoint and the Attendant handlers take over.
8. If no other condition of the selection step is true, then the call is processed as an internal call and
System_InitiateCallRequest ends. If the internal extension is to a station group, then control is
passed to the SystemCompleteStationGroupCall subroutine handler. When control returns to
System_InitiateCallRequest, a variable is checked to see if the call was placed to the station group.
If so, this handler ends. Otherwise the Main Menu plays to the caller and their client displays
Invalid Extension in the Name column of My Interactions. System_InitiateCallRequest ends.

NAVIGATING AN OUTBOUND CALL SYSTEM_STATIONOFF HOOK

Event That Starts the Process Placing a call from a SIP station generates Station Off Hook event.
Purpose Allow multiple methods of making outbound calls.

3-03Default Handlers 2017, Interactive Intelligence, Inc.


Handlers:
System_StationOffHook This handler starts when a dial string is sent from a SIP device. In the
case of an IP phone sending a dial string may mean that the user actually presses Send on their
SIP phone when they are ready to dial a number that they have keyed in or that the dial-string
entry timeout on the phone determines that the number to be dialed is complete and sends that
number to IC. The IP phone itself may also have its own dial plan, in which case the phone will
automatically Send the dial string if the user dials a number that matches one of its dial plan
entries.
This handler determines if there is a call waiting to be picked up. If there is a call waiting to be picked
up, that call is connected. It also checks to see if the IC users client is configured to automatically
connect to held calls when the station goes off- hook. If so, and there is a held call, that call is
connected. Otherwise, dial tone is played and the caller can dial a number. When dialing, the caller can
enter account and/or authorization codes before dialing, if necessary. The Station Place Call step then
generates an Outgoing Call Request event that will start the System_InitiateCallRequest handler.
CustomStationOffHook Modify this handler to add customizations to the System_
StationOffHook handler.
Exit Conditions:
If there is a call alerting, the call is connected and this handler ends.
If a call is on hold, and this IC users client is configured to automatically connect to held calls
when the phone is picked up, the call is connected and this handler ends.
If the caller presses *, SystemIVREscape is called and this handler ends.
If an account code is required and either not entered or not valid, the call is disconnected and
this handler ends.
If the caller dials #, the call is disconnected and this handler ends.

NAVIGATING AN OUTBOUND CALL SYSTEM_INITIATECALLREQUEST

Event That Starts the Process Outgoing Call Request Event.


Purpose Place outbound calls.
3-04Default Handlers 2017, Interactive Intelligence, Inc.
Handlers:
System_InitiateCallRequest This handler places an intercom call or a call on an outside line. This
handler is started when a call is placed using the Interaction Desktop. It is also started after
System_StationOffHook completes when a call is placed from a station.
If the I3DialPlan subroutine determines that the user does not have security rights to place the call,
this handler plays a prompt for the user explaining that the caller does not have security rights to
place the call. If the I3DialPlan subroutine determines that the number dialed is not a valid extension,
this handler plays a prompt for the user explaining that the number dialed is not a valid extension.
Exit Conditions:
If the call is to a valid extension and the user has security clearance, the intercom call is placed
and this handler ends.
If the call is to a station group extension, it is passed to the SystemCompleteStationGroupCall
handler and this handler ends.
If the call is to an external number and the user has security clearance, the call is placed on an
outside line and this handler ends.
If a Dial Plan failure occurs, this handler ends.

System_InitiateCallRequest calls the following subroutines:


CustomInitiateCallRequest Modify this handler to add custom behaviors for outbound calls.
As an example, the PIN code scenario discussed earlier could implement a customized PIN
challenge for all outbound call attempt during certain hours. Currently this handler returns
bTransferred = False. Any modifications you make to this subroutine are not overwritten when
you upgrade to newer versions of Interaction Center.
SystemIVRCompleteIntercomEscape This IVR (Interactive Voice Response) subroutine is
called any time a caller presses the escape key (*) or if the dial string is empty.
I3DialPlan I3DialPlan serves several purposes. One purpose is to pass dial strings to the
Interaction Administrator Dial Plan Configuration to determine the classification of the
telephone number (that is, emergency, intercom, 900 number, toll-free, and so on). Another
is to determine if the user or station placing the call has permissions to dial numbers in that
classification. Do not modify I3DialPlan. It is designed to work with Interaction Administrator
phone number classifications. If you change this handler, Interaction Center may not process
outgoing calls correctly.
RegionalDialPlanEx If the system is using the Enhanced Dial Plan (that is the platform is
HMP and the administrator has Locations defined in the Regionalization container in IA) then
this subroutine is called to classify the call.
PlayEntityNameEx This plays the user name as part of a message if the caller does not have
the appropriate rights for the type of call.
InteractionAttendantEntryPoint If the caller dials an invalid number, the call is routed to
InteractionAttendantEntryPoint and processed by the default auto attendant menus.
SystemCompleteStationCallGroup If the call is to a station group, this handler will take over
processing of the call.
SystemIVRConfirmEscape This handler determines if the call should be routed to the
system queue, or to an operator, or whether the call should just be disconnected (for example
due to a timeout).
SystemProcessPersonalRules If there are any Personal Rules set by the user in their Client which
apply to outbound calls, this subroutine determines the Actions which should apply to this call.

3-05Default Handlers 2017, Interactive Intelligence, Inc.


Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following labs in your lab manual:
Lab 15: Navigating Outbound Calls

3-06Default Handlers 2017, Interactive Intelligence, Inc.


3.2 Incoming Calls

INCOMING CALL FLOW


The incoming call process begins when a call comes in to the IC server from the external
telephone network.
From an architectural point of view this is what IC does during an inbound phone call:
1. A call comes in over the external telephone network.
2. That call arrives on the SIP hardware or software.
3. The SIP hardware or software communicates through an API to Telephony Services (TS).
4. Telephony Services sends a request event to Notifier that the call should be put on the
System queue.
5. The Notifier sends the request to the Queue Manager.
6. The Queue Manager puts the call on the System Queue.
7. Queue Manager generates a response event telling Notifier that the request has been processed.
8. Notifier forwards the event to Telephony Services.
9. Telephony Services generates a notification event that a call has been put on the System Queue.
10. Notifier sees this event and forwards it to all interested modules, including the Interaction
Processor (IP) subsystem.
11. Interaction Processor starts the handler with the Incoming Call initiator.
12. The handler runs, sending request events (generated by the steps in a handler) through Notifier
to Telephony Services. These messages tell Telephony Services to pick up the call, play audio
to the call, gather IVR input from the call, and so on. Telephony Services generates response
events which are sent by Notifier back to the handler. The handler and Telephony Services
communicate in this way.
13. The handler tells Telephony Services (using a request event passed through the Notifier) to
transfer the call to a specific User queue. This is the last of the requests from this handler.
14. The handler ends.
15. Telephony Services tells the Queue Manager (using a request event passed through the
Notifier) to transfer the call to a specific User queue.
16. The Queue Manager places the call on the specified User queue and generates a notification
event of the change in the queue.
17. Telephony Services generates a notification event that a call has been put on a non-system queue.
18. Notifier forwards the notification event to Interaction Processor.
19. Interaction Processor starts a handler that performs actions to calls on non- system queues.
20. The handler determines that the queue is a user queue.
21. The handler communicates (using a request event) with Queue Manager to determine which
workstations are monitoring the user queue that contains the call.
22. The handler requests that TS change the calls state to Alerting.
23. TS generates a notification event that the calls state has been changed to Alerting.
24. The Notifier tells each Interaction Desktop, monitoring the specific User queue, that a call is
alerting in that queue. The Interaction Desktop plays a sound on the computer, pops a screen,
or performs some other action to alert the person monitoring that User queue.
25. (At same time as 24)The handler tells Telephony Services (using a request event) to ring
the telephones.
26. Telephony Services rings those telephones.

3-07Default Handlers 2017, Interactive Intelligence, Inc.


QUEUES

Interaction Center stores calls in areas of the system called queues. There are several different
kinds of queues, but you can think of each of them as a holding place or bucket with an
effectively infinite capacity.
System Queue When a call first comes into Interaction Center, an Incoming Call Event is
generated. When this happens, the call is placed on the System Queue until Interaction Center
determines that calls destination.
Non-System Queue If the caller dials an extension, a Call to Non-System Queue Event is generated.
Interaction Center looks up the numbers dialed and matches them with a user, a station, a station
group, or an ACD workgroup and directs the call to the appropriate location. (There are other queues,
such as line queues, but we will focus on the ultimate destination of the call in this discussion.)

NAVIGATING INCOMING CALLS SYSTEM_INCOMINGCALL


The following chart illustrates the progression of an incoming call through the system. Some of
these steps are reached as a result of conditions which may or may not apply to a particular call.
For example, the SystemIncomingSIP and SystemIncomingTAPI subroutines are only called if the
protocol of the incoming call is SIP or TAPI. However, for clarity, these steps have been represented
sequentially in the diagram.

3-08Default Handlers 2017, Interactive Intelligence, Inc.


Object That Starts Process Any Incoming Call
Purpose Answer an incoming call and determine how to process it.
Handlers:
System_IncomingCall This handler answers an incoming call when it first comes in to Interaction
Center. System_IncomingCall then calls several subroutines, several of which are customization
points, to process the new call. This handler then calls InteractionAttendantEntryPoint where
prompts are played and the key presses of the caller are evaluated.
The Answer step establishes a connection with an incoming call. This step fails if the Call ID is not valid.
System_IncomingCall calls the following subroutines:
InteractionDirectorEntryPoint Determines if Interaction Director is installed, and if so, this
first call to InteractionDirectorEntryPoint performs any pre-answer tasks required by Director.
The second call to InteractionDirectorEntryPoint performs any post-answer processing of the
call. If the Director handlers transfer the call, then processing within System_IncomingCall
ends. If Interaction Director is not installed, then the call continues to be processed by
System_IncomingCall.
CustomAnswer This subroutine is for you to add custom answering processing before a
call is answered. By default, it assigns Answered a value of false and ends. If you change this
subroutine so that Answered has a value of true, System_IncomingCall ends. Any customizations
you make to this handler will not be overwritten in future Interaction Center upgrades.

Not allowing System_IncomingCall to complete can cause the loss of some call processing. You may
CAUTION
need to duplicate this functionality in CustomAnswer if System_IncomingCall is not going to execute
this functionality.
SystemIncomingCallAnalysis This subroutine calls the CustomIncomingCallAnalysis
subroutine which evaluates whether an unanswered incoming call resides on a line that is
marked for outbound calls only. CustomIncomingCallAnalysis retrieves the LineName attribute
from the call object and looks up the line in Directory Services to determine if it is Inbound,
Outbound, or Inbound/Outbound. If the line is Outbound only, the call is disconnected. If the line
is Inbound, or Inbound/Outbound, this subroutine ends and the call continues as normal.
CustomIncomingCall Modify this handler to add custom behaviors for incoming calls after
they have been answered. These behaviors can be a custom greeting, call screening, or some
other behavior. Currently this handler returns bTransferred = False. If you add customizations
that could send the call out of the normal IVR, be sure to set bTransferred = True so that
System_IncomingCall ends.
Any modifications you make to this subroutine are not overwritten when you upgrade to newer
versions of Interaction Center.
SystemDNISRouting This handler examines the number dialed on an inbound call and tries
to match it against a number in the Interaction Administrator DNIS routing table. If a match
cannot be found, this handler ends. If a match is found, this handler looks up and determines
the queue type. If the number is found, a Blind Transfer step is called that generates a Call
Offering Non-System Queue event which starts the System_CallOfferingNonSystemQueue
handler. Otherwise, control is returned to System_IncomingCall.
InteractionAttendantEntryPoint Passes the call on to the Interaction Attendant handlers
for processing.
SystemIncomingTAPI If the Protocol ID of the incoming call is TAPI, this subroutine is called.
This situation would only apply when IC is installed to work with Cisco CallManager. Otherwise,
control is returned to System_IncomingCall.
SystemIncomingSIP If the Protocol ID of the incoming call is SIP, this subroutine is called.
Otherwise, control is returned to System_IncomingCall. SystemIncomingSIP provides the
subroutine CustomIncomingSIP as a customization point for inbound SIP calls.

3-09Default Handlers 2017, Interactive Intelligence, Inc.


Exit Conditions
When the call is sent to a non-system queue, the handler ends.
When Interaction Director takes control of the call, the handler ends.
When Interaction Attendant takes control of the call, this handler ends.
If the call is routed to another site in a Multi-Site configuration, this handler ends.
If the call is a TAPI call from CallManager, or the call is a SIP call, the appropriate subroutine
takes control of the call, and this handler ends. Otherwise, control is returned to System_
IncomingCall.
If the DNIS number matches a number in the DNIS table (configured in Interaction
Administrator), SystemDNISRouting takes control of the call and this handler ends.

NAVIGATING INCOMING CALLS


SYSTEM_CALLOFFERINGNONSYSTEMQUEUE

Event That Starts the Process A Call Offering Non-System Queue event.
Purpose This handler routes a DID call to the appropriate Non-System Queue.
Handlers:
System_CallOfferingNonSystemQueue This handler starts any time a Call to Non-System
Queue event is generated. (The Blind Transfer tool generates this event.) This handler
determines the type of queue the call should be sent to and starts an appropriate
subroutine (either SystemIVRCallOfferingStationGroupQueue, SystemIVRStationQueue,
SystemIVRWorkgroupQueue, or SystemIVRUserQueue) to process the call.
When the call returns from the appropriate subroutine, System_CallOffering- NonSystemQueue
checks to see if the call is intended for voice mail and calls the voice mail subroutine to process it.

3-10Default Handlers 2017, Interactive Intelligence, Inc.


System_CallOfferingNonSystemQueue calls the following subroutines. For clarity, not all
subroutines called by System_CallOfferingNonSystemQueue are listed.
InteractionDirectorEntryPoint Determines if Interaction Director is installed. If Interaction
Director is installed, Interaction Director handlers take control of the call. If Interaction Director
is not installed, control is passed back to System_CallOfferingNonSystemQueue.
InteractionAttendantEntryPoint If this call is to an ACD workgroup, this handler begins the
ACD processing. Otherwise, control is passed back to System_CallOfferingNonSystemQueue.
SystemIVRCallOfferingStationQueue This subroutine processes calls to station extensions.
If the station is connected to another call, this handler determines how to handle the call
(connect it into a conference, forward the call, send to voice mail, and so on). If the station is not
connected to another call, SystemIVRStationQueueAlert is called to ring the station.
SystemIVRCallOfferingStationGroupQueue This subroutine is similar to
SystemIVRCallOfferingStationQueue. It processes calls to station group extensions, rather than
station extensions.
SystemIVRCallOfferingWorkgroupQueue This handler looks up the time- out value for a
specific queue. It then queries the call type and branches depending upon whether the call is a
telephone call, chat, or some other type of interaction in order to process the interaction. If it is
a call, SystemIVRCallOfferingWorkgroupQueue checks to see if the call should be recorded. It
then either sends it to voice mail or passes the call on to SystemIVRWorkgroupQueueAlert.
SystemIVRCallOfferingUserQueue This handler checks to see if the user is alertable. If so,
the call is passed to the SystemIVRUserQueueAlert to alert the user. Otherwise, the call will
be processed depending upon the status of the user and/or client settings (that is forwarded to
another number, sent to voice mail, and so on).
CustomCallOfferingNonSystemQueue This is the customization point provided for custom
processing of calls reaching the System_CallOfferingNonSystemQueue handler.
Voicemail This subroutine is called if the ForwardVoicemail attribute is set in the attributes of
the incoming call.

Exit Conditions:
If the queue type is Workgroup, SystemIVRCallOfferingWorkgroupQueue is called and this
handler ends.
If the queue type is Station Group, SystemIVRCallOfferingStationGroupQueue is called and this
handler ends.
If the queue type is Station, SystemIVRCallOfferingStationQueue is called and this handler ends.
If the queue type is User, SystemIVRCallOfferingUserQueue is called and this handler ends.
If the queue identifier is not valid, the Query Queue Type step will fail and this handler ends.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following labs in your lab manual:
Lab 16: Navigating Incoming Calls
Lab 17: Understanding p_bTransferred

3-11Default Handlers 2017, Interactive Intelligence, Inc.


Chapter

Interaction Attendant
4
Call Processing and Interaction Attendant

www.inin.com/education 2017, Interactive Intelligence, Inc.


4.1 Call Processing and Interaction Attendant

WHAT IS INTERACTION ATTENDANT?


Interaction Attendant is a utility to help you create and maintain automated attendant menus An
automated attendant automatically answers a call and prompts the caller to make menu choices.
Attendant then routes the call according to the choice made by the caller. Callers select an option by
pressing a key on their telephone keypad.
Interaction Attendant differs from traditional Interactive Voice Response (IVR) applications in that
it does not require modification of handlers to perform basic IVR functions. While Interaction
Attendant does offer database access, its processing is not as complex as a full IVR application.
Yet the power of Interaction Attendant does provide the ability to create sophisticated automated
attendant menus.
Interaction Attendant provides complete control over what happens when each key is pressed
For example, you can play a prerecorded message, route the call to a queue, send a fax, look up
information in a database, or pass control to a submenu. Interaction Attendant predefined operations
can be linked together any way you want to create a sophisticated Interaction Attendant menu.
When you start Interaction Attendant and connect to an Interaction Center server, a tree structure
will appear in the left panel This panel contains profiles, schedules, and menus for each
connected server. When you click a node in the tree, you can edit the properties of the selected
item, or add more items to the tree. Simple rules determine the order of items in the tree, and the
options that are available.
To build an Interaction Attendant menu, you add, arrange, and configure items in the tree. It is that easy.

FEATURES OF INTERACTION ATTENDANT


Interaction Attendant processes all incoming calls. Interaction Attendant provides the tools needed
to construct sophisticated automated attendant menus. Its features allow you to perform various
functions, such as:
Customize the way inbound calls are answered (via DNIS, ANI or line name) by creating
unlimited menu levels and menu transfers.
Edit menus, schedules, and profiles for many IC servers at once. Profiles, schedules, and menu
operations are displayed in an easy-to-understand tree structure. The tree visually indicates
when someone else is editing the server configuration. In addition, errors and default conditions
are visually flagged using special icons and colors.
Record prompts using an ordinary telephone. Prompt playback is supported in most
menu operations.
Import and export menu configurations. You can easily back up a server configuration and
restore it later.
Interact with data sources using the Attendant database operations. For example, you can
prompt users to enter data and save their entries in a database.
Customize call processing according to time sensitive parameters: month, day, day of week,
hour, or minute for after hours/holiday call routing. Using the Logical Transfer operation, you
can branch to menus based on data entered by a caller, data about the current call, the current
time, data about a workgroup, or data in a database.
Schedule menus to run at different times or schedule menus based on incoming call criteria, such
as DNIS, ANI, or line information. You can create unscheduled menus and activate them from a
touchtone telephone.
Route calls to any system workgroup queue, user queue, or station queue.

4-02Interaction Attendant 2017, Interactive Intelligence, Inc.


Play an audio file in response to a particular menu option.
Prompt the caller to enter data, such as a fax number.
Send a fax to a number entered by a caller.
Receive fax transmissions. Automatic fax Detection at a menu allows a workgroup or main
number to function as a fax number as well.
Route a call to the appropriate unified messaging inbox.
Transfer a call to an external number.
Customize voice prompts and record greetings.
Direct calls to the Dial by Name subsystem.
Configure flow-of-control. You can define error handling at the schedule and form level, and
use Action when Finished branching options. When a menu operation finishes, you can return
control to the previous menu, disconnect, or pass control to any profile, schedule, or menu you
define for the current server.
Interface with the powerful IC handler customization subsystem by sending a call to an
Interaction Handler from a menu option.

HOW DOES ATTENDANT WORK?


Interaction Attendant uses profiles and schedules to determine which operations to perform to
interact with a contact.
The basic steps are as follows:
1. The IC server gives Interaction Attendant an interaction to process. Most often, the interaction
is an inbound call, or a call that was routed to an operator. But it could be an outbound call
placed by Interaction Dialer or a custom telephony application. Interaction Center also includes
the ability to process inbound emails, using Attendant logic, by opening Attendant in a separate
email- processing mode.
2. Attendant analyzes the call to accumulate information about it. It determines whether the call
is inbound or outbound. If the call is inbound, it acquires the telephone number that was dialed
(DNIS), the telephone number of the caller (ANI), and the line or line group that the call is on.
3. Profiles Attendant compares the call (or other interaction, for example email) characteristics
to predefined profiles for that server. It gives control over the call (or other interaction) to the
profile that most closely matches the call.
A profile is a collection of predefined call characteristics that Attendant compares to a call to
figure out how to process it.

Suppose that your company offers two levels of technical support: Silver and Gold. Silver
EXAMPLE
members call 555-1111, and Gold members call 555-2222. To tell Attendant how to handle
support calls, you would use Attendant to create an inbound profile for each telephone number.
Each profile filters calls to match one of the numbers. When callers dial 555-2222, their call is
processed by the profile for Gold support. When callers dial 555-1111, their call is processed
by the profile for Silver technical support. In this scenario, Attendant uses Dialed Number
Identification Service (DNIS) to determine the number dialed. Since Attendant knows the dialed
number, it can perform unique processing on the call. For example, it can play special messages
or offer alternate menu choices.
The main idea is that profiles are compared to calls to see if the call matches a profile
characteristic of some sort. For example: Was this particular number dialed? Did they call our
800 number? You can define as many profiles as you need to define.
Here is another scenario: Suppose that Marketing needs special call routing. They want to
automatically route calls from their biggest customer directly to the person who manages that
account. To catch these calls, you would define a profile that examines the telephone number of the
caller, rather than the number dialed. A profile of this type uses a process called Automatic Number
Identification, or ANI for short. ANI is sometimes called Caller ID, and it is the opposite of DNIS.
DNIS indicates the number that was called. ANI provides the telephone number of the caller.

4-03Interaction Attendant 2017, Interactive Intelligence, Inc.


Profiles do not have to be specific. They can examine a wide range of incoming call
characteristics, using wildcards, and a combination of ANI, DNIS, and line criteria. When a
profile is evaluated, criteria are ANDed together to select calls to process. If more than one
criterion is specified, all of the criteria must be met before the call matches that profile. But
what happens if you do not create a profile for every conceivable type of call?
Default Profile The answer is that Attendant provides a default profile that catches calls that do
not match user-defined profiles. You can customize a default profile to play a .wav file, but its filtering
criteria are dimmed. Because the default profile does not filter by these criteria, it will match all calls
that do not match any custom profiles.
4. Schedules But what if your best customer calls at midnight, when the account rep is not
there? Or, what if someone calls Technical Support on Christmas, when the entire company
is on holiday? What if it snows, and you have to suspend operations for a day or two? As you
can see, operations are time- sensitive. Attendant handles these considerations rather nicely.
Once a matching profile is given control of a call, Attendant evaluates schedules to select an
appropriate set of operations to perform.
A schedule determines whether a menu of operations is active based upon a date, range of
dates, time, or special event.
A profile can have many schedules attached to it. Schedules stipulate when a menu of
operations can run. You can define schedules to handle recurring events, holidays, or special
situations, such as your regular business hours, after-hours support, or an office closing due to
poor weather conditions. But what if you do not think of every contingency?
Default Schedule - You guessed itevery profile has a default schedule. Attendant creates it for
you automatically. The menu attached to a default schedule is given control of the call when no
other schedule in the profile has precedence.
A default schedule ensures that all calls are processed if a call arrives during a period that is
undefined by custom schedules.
Since the default schedule is designed as a catch-all, you cannot edit it to define a start or end
date, or to specify daily, weekly, monthly, yearly, unplanned, or system events. Those items can
only be configured in a custom schedule form. When a call flow is passed to a schedule, the
menu operations of that schedule are executed. Up until now, call processing has been largely
invisible to callers. But from this point forward, callers interact with menu operations attached
to the schedule. Attendant allows you to define as many schedules as needed to perform
appropriate actions for a specified date, time, or situation.
You can even set up unplanned schedules and activate them over the phone. For example,
you can create an unplanned schedule for a snow day to tell customers that your business is
closed. In a weather emergency, you can remotely activate the schedule from home.
Multiple schedule matches if there are multiple schedules which exactly match a particular
call, Attendant will choose the schedule positioned highest in the interface tree structure.
5. Menus Menus are created when you associate operations with a schedule. Attendant
provides dozens of operations that help you build menus. For example, you can create menus
that allow callers to dial by name, dial by extension, or transfer a call. Attendant even provides
an operation that creates a submenu. However, Attendant is not limited to mundane tasks.
For example, it can obtain data from a caller, look up information from a database, and update
records. If you need functionality that Attendant does not offer, you can call custom handlers
from Attendant. Handlers can perform just about any conceivable data processing task. They
extend the IC platform to meet unique business requirements.
6. Operations Since profiles merely set up comparisons, they do not carry out actions, such as
transferring a call. The tasks that Attendant can perform are called operations. Operations do
work of some sort, such as prompting a caller to enter an account number or reading back an
account balance that was retrieved from a database.

4-04Interaction Attendant 2017, Interactive Intelligence, Inc.


INTERACTION ATTENDANT HANDLERS
IntAtt handlers Any handler that begins with IntAtt is a handler used internally for Interaction
Attendant functionality. These handlers must NEVER be modified.
InteractionAttendantEntryPoint This handler is called from many system handlers. This handler
contains a selection step that will determine from which handler it was called and branch based upon
that information.

This handler must NEVER be modified.


CRITICAL

CustomSubroutineInitiatorRouter.ihd This handler is used with the Subroutine Initiator operator


in Interaction Attendant to transfer control to a subroutine. It provides a means for customizable
behavior through Interaction Attendant.
The Subroutine Initiator operator provides a pathway into the Interaction Center regular handler
set. When a caller selects a menu item associated with the Subroutine Initiator, it generates
a notification event that results in the calling of the IntAttSubroutineInitiator.ihd subroutine,
which then calls the CustomSubroutineInitiatorRouter.ihd subroutine. The call ID and the value
specified in the Subroutine Name field are passed to this handler. Add a Selection statement in
CustomSubroutineInitiatorRouter.ihd, which is used to evaluate the Subroutine Name value and
exits according to the appropriate value. When you create a custom subroutine, add an exit path
to the Selection step in CustomSubroutineInitiatorRouter.ihd that will call the subroutine that
contains your custom functionality. When the handlers no longer have control of the call, or if the
caller presses a valid escape key within your custom handlers, the call returns to the Interaction
Attendant menu structure in the same location from which it left.
This subroutine is discussed in detail in Chapter 5: Customizing the System.
Since much of the Interaction Attendant functionality is based upon complex Directory Services
CAUTION
lookup handlers, never change any handlers that begin with IntAtt. Interaction Designer will not
prevent you from making modifications to these critical system handlers. Even small changes made
to these handlers can cause your automated attendant to stop functioning.

4-05Interaction Attendant 2017, Interactive Intelligence, Inc.


Review Questions
Complete the review questions for this module in your study guide.

Labs
There are no labs associated with this module.

4-06Interaction Attendant 2017, Interactive Intelligence, Inc.


Chapter

Customizing the System


5
Customizing Handlers
Custom ACD Processing
Database Tools
Prompt Libraries

www.inin.com/education 2017, Interactive Intelligence, Inc.


5.1 Customizing Handlers

CUSTOMIZING YOUR SYSTEM


There are essentially three approaches to customizing an Interaction Center system:
Interaction Attendant
Subroutine Initiator Operator
Customization Points

Interaction Attendant has many operators that can be used to customize the automated attendant
for an IC system. With Interaction Attendant, you can perform transfers, database lookups, get user
input, send and receive faxes, and much more.
The Subroutine Initiator Operator is an operator in Interaction Attendant that works with
the CustomSubroutineInitiatorRouter handler to allow you to call subroutines from within
Interaction Attendant.
Customization points are calls to customization subroutines. Customization subroutine calls will always
be in the same location to ensure that they are not overwritten by future hotfixes or service updates.

SUBROUTINE INITIATOR OPERATOR

The Subroutine Initiator Operator within Interaction Attendant provides a means of calling
subroutines from within an Interaction Attendant menu, making Interaction Attendant extensible.
The Subroutine Initiator properties specify the name of the subroutine to be called when this
operator is selected, either by a number press from a caller or a call from another menu item. This
functionality is achieved by the CustomSubroutineInitiatorRouter.ihd handler which is modified to
contain a selection step to invoke the functionality of the subroutine. Once the selection is added to
the selection step, connect it to your subroutine call step.

5-02Customizing the System 2017, Interactive Intelligence, Inc.


CUSTOMIZATION POINTS
Customization points are subroutines in which customizations can be made that will not be
overwritten by future Interaction Center upgrades.
Interactive Intelligence STRONGLY recommends against modifying base system handlers that
ship with our products. Use the customization points as much as possible. To place a request for
a new customization point, submit the request to ideas.inin.com. Using the customization points
is a best practice for a maintainable system from SU to SU and version to version. Modifying base
handlers introduces risk when applying updates and will require migration effort to maintain your
customizations with each update.
If you choose to modify any of the base handlers, it is at your own risk. When Support determines
that an incident is due to modification of a base handler, they will close the case. Also, since the
Service Update process is automated, a customized base handler can be overwritten any time an
SU is applied, and your custom functionality will be gone until you merge your changes back into
the new base handlers supplied in the SU.

5-03Customizing the System 2017, Interactive Intelligence, Inc.


CUSTOMIZATION CONVENTIONS
As mentioned previously, there are specific areas within many default handlers for customizations. It is
important that you follow the conventions listed here to protect any customized solutions from deletion.
Use customization points The customization handlers listed on the previous pages are provided
specifically for customizing the system. Altering base handlers is not recommended. Interactive
Intelligence STRONGLY recommends against modifying base system handlers that ship with our
products. Use the customization points as much as possible. Submit ideas for new customization
points at ideas.inin.com. Using the customization points is a best practice for a maintainable system
from SU to SU and version to version. Modifying base handlers introduces risk when applying
updates and will require migration effort to maintain your customizations with each update.
Handler development usually requires extensive time and effort. When updates to the software
are applied, base handlers can be overwritten. If a handler developer has altered a base handler
that has been overwritten by an update, then all the customizations are lost and must be recreated.
The handlers supplied as customization points are not overwritten for any update and therefore all
customizations remain intact after an update to the system.
Store all new and modified handlers in the Custom folder Sometimes the handlers created as
customization points are not the best solution for customization. When it is necessary to create a
handler, be sure to store it in the Custom folder. The Custom folder is not altered during any updates
to the system so custom solutions stored here remain intact. It is recommended that you DO NOT
store new custom handlers in any of the other IC system folders. These folders may be overwritten
during an update causing customizations stored in these folders to be lost.
Create a Work in Progress folder While developing or modifying handlers, store them in this
Work in Progress folder until they have been thoroughly tested and are ready to be put into
production. At that point, move them into the appropriate folder and publish them. By using a
separate folder for handlers that are being developed or tested, you cannot mistake them for a
handler that is in production.
Using this standard, eliminates confusion and prevents the possibility of overwriting a production
handler with an untested handler that is being modified.

USING VARIABLES
Previously, we defined a variable as a symbol or name that stands for a value. In handlers, there are
three kinds of variables that you can use:
Local variables A local variable can only be used in the handler in which it is defined.

The value of local variables can be passed through to subroutines only if they are defined in the
subroutines initiator. Local variables are created by doing one of the following:
Using an Assignment step to define the variable.
Using the Variables palette to define the variable.
Using the Initiator to define the variable.

5-04Customizing the System 2017, Interactive Intelligence, Inc.


Global variables A global variable can be used in any handler on the IC system on which it is created.

Global variables are defined in the Global Variable Manager which is accessed either through
File>Import Global Variables... or by right-clicking in the Variables palette and selecting Import
Global Variables...
Global variables are locked throughout the duration of a handler instance. For this reason, create
subroutines that read and/or modify a global variable to minimize the time the global variable is locked.
Server Parameters In Interaction Administrator, you can define Server Parameters which are
available on the IC server on which they are defined. To access the parameter value from within a
handler, you use the Get DS Parameter tool. You can also create the parameter using this tool.

Server Parameters are typically used for values that may need to be changed by an IC Administrator.
The administrator can change the value in Interaction Administrator without ever opening
Interaction Designer. Once the value is changed, any handler that references the parameter will
read the new value. Server Parameters are always of string data type.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following labs in your lab manual:
Lab 18: Using CustomSubroutineInitiator
Lab 19: Using Server Parameters
Lab 20: Team Build

5-05Customizing the System 2017, Interactive Intelligence, Inc.


5.2 Custom ACD Processing

AUTOMATIC CALL DISTRIBUTION OVERVIEW

Automatic Call Distribution (ACD) with Multimedia Queuing is a system that intelligently routes
interactions (calls, Internet chat sessions, call-back requests, email, and so on) to available agents.
There is no limit to the number or size of the ACD queues configured to receive interactions.
Interaction Centers ACD quickly finds the best match between agent and interaction by calculating
agent scores and interaction scores. These scores are calculated by a subsystem on the Interaction
Center Server called the ACD Server. Using Custom ACD, you can configure the formula used to
calculate these scores, and customize the ACD system to meet your needs.
Simple (or Basic) ACD When an ACD workgroup has been assigned a queue type of ACD in
Interaction Administrator, interactions can be routed to an agent based upon:
Time an agent has been available
Agent cost
Agent skill proficiency
The priority of an interaction
Time an interaction has been in the queue

No handler modifications are required for this behavior.


Custom ACD When an ACD workgroup has been assigned a queue type of Custom in Interaction
Administrator, interactions can be routed to an agent based upon many possible factors, such as:
Agent skill proficiency
Agent skill desire to use
Agent cost
Time an agent has been available
Agent Attributes 1, 2 and 3
Interaction skill requirement
Interaction priority level
5-06Customizing the System 2017, Interactive Intelligence, Inc.
Time an interaction has been in an ACD Queue
Time an interaction has been in Interaction Center

The Interaction Center Custom ACD capabilities are configured through both Interaction
Administrator settings and handlers. The attributes of each agent (skills, proficiencies, cost, or other
attributes you create) are assigned in Interaction Administrator. Whether you are adding an agent,
or updating an agent profile, the change takes effect immediately.
The skill, priority, and cost requirements for an interaction are assigned through handler
modifications. Interaction Center generates a list of available qualified agents who can take the
interaction. Then Interaction Center selects the most appropriate agent to take the interaction
based on any combination of skills, cost, other attributes, and/or availability. If an interaction goes
unanswered or remains on hold too long, you can flag that interaction for special processing.
In this class, we will be focusing on Custom ACD processing.
FOR YOUR
INFORMATION

AUTOMATIC CALL DISTRIBUTION DEFINITIONS


ACD Queue A container for interactions flagged for ACD processing. You can have as many ACD
queues as you like, and there is no limit to the number of agents in a queue.
Agent A person who receives incoming interactions. Agents can have attributes such as skills,
costs, and the amount of time since they last answered an interaction. An agent can be a member of
any number of ACD queues.
Agent Score Formula The configurable formula that calculates agent scores. If there are agents
available when an interaction arrives in an ACD queue, the agent with the highest score receives the
interaction. Agent scores take into account agent, skills, cost, the amount of time that agent has been
available, and other custom attributes that you can define.
Interaction Score Formula The configurable formula that calculates the score of interactions.
Interaction scores take into account interaction skill requirements, priority, the amount of time an
interaction has been in the ACD queue, and the amount of time an interaction has been in the IC
system. If there are many interactions waiting to be answered and an agent becomes available, a score
is calculated for each interaction. The interaction with the highest score is assigned to that agent.
Interactions Interactions are telephone calls, chat calls, email, and generic objects. For purposes of
ACD processing, interactions can be assigned priorities and skill requirements. Times are also
recorded for both the length of time an interaction waits in an ACD queue and the length of time an
interaction has been in the Interaction Center system.

INTERACTION TYPES
Callbacks A callback is a request sent from a customer at a website that will generate an outbound
call to the customer from an available agent. Aside from how the call is made, this interaction is
essentially a standard telephone call.
Calls Telephone calls are the most common type of interaction routed by ACD processing.
Chats Chats can be processed in the ACD just like telephone calls with two exceptions:
Chats cannot be assigned to phone-only agents.
Chats cannot use hunt groups.
Email Workgroups can be configured to receive ACD routed email from multiple mailboxes. email
queuing is configured in Interaction Administrator in the Workgroups container. From Workgroups
properties, select the ACD page and select Routing.

5-07Customizing the System 2017, Interactive Intelligence, Inc.


All email in the Inbound Folder specified in the Mailboxes field are processed by ACD routing using
the same logic as for calls.
Agent responses contain the name of the ACD Mailbox in theFrom field. A copy will be sent to the
Sent Items folder of the mailbox designated. The workgroup queue type must be set to ACD or
Custom on the Configuration page.
If the PostOfficeServer process is ever stopped, all email objects are removed from all queues and
will be reinserted into the workgroup queues on restart and processed by ACD. The email objects
will not necessarily be routed to the same agent and any response that was in progress will be lost.
The addresses used for ACD email routing must be physical accounts. email distribution lists will not
work for ACD email routing because IA requires a message store, which distribution lists do not have.
Generic Objects (CIC only) CIC supports a generic object type for routing customer-defined
objects such as a third-party chat system, a video, or a workflow document to agents in workgroups.
These generic objects function like other interactions within Interaction Desktop.
A generic object appears in the Interaction Desktop, My Interactions tab just like other
interactions. When you click it, the application or document pops open in Interaction Desktop. It
can be transferred, disconnected, and so on, like other interactions.

5-08Customizing the System 2017, Interactive Intelligence, Inc.


AUTOMATIC CALL DISTRIBUTION PROCESS

The Interaction Center ACD is designed to intelligently match interactions to available agents under
two scenarios:
Interactions < Agents The first scenario occurs when an interaction arrives in the ACD queue and
there are many agents available to answer the interaction. In this scenario, the goal is to select the
most appropriate agent for that interaction. You configure the ACD processing to select the most
appropriate agent based on skills, cost, and the amount of time an agent has been available. You can
also create custom attributes on which the agent is selected.
Interactions > Agents The second scenario occurs when there are many interactions waiting to be
picked up from the queue and an agent becomes available. The goal for this scenario is to select
the most appropriate interaction to present to the available agent. Again, you configure the ACD
processing to select the appropriate call based on agent skills, interaction priority, and amount of
time an interaction has been waiting in the ACD queue or the Interaction Center system.

5-09Customizing the System 2017, Interactive Intelligence, Inc.


INTERACTIONS < AGENTS

1. An interaction arrives.
Each time an interaction arrives in Interaction Center, it is evaluated and routed to the
appropriate queue. Possible queues are user queues, workgroup queues, station queues, and
ACD queues. Any interaction sent to an ACD queue is flagged for ACD processing.
2. A list of available agents is generated.
Every agent with a status of Available who is not already engaged in an Interaction is added to
the list of agents that could answer the interaction.
3. The agent list is filtered based upon skill requirements.
If the interaction requires a skill, agents without the minimum skill requirements are removed
from the list.
4. Agent scores are calculated.
Now Interaction Center calculates a score for each agent in the list using the agent score formula.
5. The agent with the highest score is selected to receive the interaction.

INTERACTIONS > AGENTS

5-10Customizing the System 2017, Interactive Intelligence, Inc.


1. An agent becomes available.
An agent becomes available, either by finishing a previous interaction, logging on to Interaction
Center, or setting the Interaction Desktop status to Available. In any case, the agent is ready to
answer another interaction.
2. A list of waiting interactions is generated.
Interaction Center generates a list of all the interactions in the ACD queue waiting to be
answered. Each of these interactions was assigned minimal skill requirements and priority when
it entered the ACD queue.
3. Interactions are filtered based upon skill requirements.
If an interaction requires a skill at a level that the available agent does not possess, the
interaction is removed from the list
4. Interaction scores are calculated.
5. The interaction with the highest score is selected and presented to the available agent.

AUTOMATIC CALL DISTRIBUTION ATTRIBUTES

Skills A skill is an agent attribute, and each agent can have one or more skills. (Agents can also
inherit one or more skills when they become a member of a certain workgroup.) Along with each
skill is a proficiency level. Proficiency levels are used in calculating both agent and interaction
scores. Interactions can require minimum proficiency levels for one or more skills. If an agent has a
Microsoft Word skill with a proficiency of 50, that agent will not be assigned to any interactions with
a Microsoft Word proficiency requirement of 51 or greater.
Also, associated with each skill is a measure of that agents desire to use that skill. (Alternately,
desire to use could be the organizations desire for an agent to use that skill.) This value can also
be used to increase agent score, and therefore increase chances of the agent for receiving an
interaction that requires that skill.
Attributes Attributes are agent and interaction characteristics such as skills, cost, and priority.
Agent attributes are assigned in the Interaction Administrator.
Interaction attributes are assigned and modified in handlers. A weight is associated with each
attribute that determines how that attribute affects the agent or interaction score. Interaction
Center provides the option of creating custom agent attributes.
5-11Customizing the System 2017, Interactive Intelligence, Inc.
Cost Cost is an agent attribute. Agent cost can be used in calculating agent scores. You can
configure your ACD to prefer agents with low cost or high cost. While cost can be related to agent
salary, you might assign a high cost to agents that will take longer to determine a solution. It might
also be cost to the customer.

INHERITED SKILLS

Inherited Skills When a user belongs to a workgroup, they inherit all the skills for that workgroup.
These skills appear in the Inherited Skills box. If the user has their own user-specific skills, they
appear in the skills box.
Multiple Workgroups When ACD Server evaluates required skills, it first looks for skills that were
explicitly assigned to that agent from Interaction Administrator.
If the required skills were not explicitly assigned, ACD Server looks at the skills that the agent
inherited from any workgroups to which he or she belongs.
The agents entire set of skills is used to evaluate an interaction on a workgroup queue.

5-12Customizing the System 2017, Interactive Intelligence, Inc.


CONFIGURING A WORKGROUP FOR CUSTOM AUTOMATIC CALL
DISTRIBUTION IN INTERACTION ADMINISTRATOR

1. Create a workgroup.
2. Create a queue.
3. Select a queue management type.
4. Activate the workgroup.
5. Assign members.
6. Assign agent utilization.
Create a Workgroup From Interaction Administrator, create a workgroup in the Workgroups
container.
Assign a Queue On the Configuration tab, select the Workgroup has Queue check box for this
workgroup to receive interactions. If this check box is not checked, the workgroup will not have a
queue and will not be able to receive interactions.
Assign a Queue Management Type A Queue Management Type defines how a workgroup will
behave when an interaction reaches the queue. This feature allows you to set up simple ACD and
hunt groups with no handler modifications.
ACD This is simple (or basic) ACD requiring no handler modifications. When an interaction
enters the workgroup, it will be assigned to an agent based upon the following properties:
Who has been in Available status the longest
The cost setting in Interaction Administrator
The proficiency level of a skill
Sequential When an interaction enters the workgroup, individual members of that workgroup
who are logged on and available will be alerted. Members are alerted to the interaction in the
order specified in Workgroup Configuration properties> Members page > Currently Selected
Users. If setting up a Hunt Group, check the Maintain order on this page.

5-13Customizing the System 2017, Interactive Intelligence, Inc.


Group Ring When an interaction enters the workgroup, each user who is logged on and in an
available state will be alerted. If the interaction times out, it is transferred to voice mail.
Round Robin Similar to linear hunt groups, Round Robin remembers the last user who was
assigned a call. When a new call comes into the queue, the system will start with the next user in
the list to check availability. The system cycles through the list once looking for an available user.
Custom When an interaction enters the workgroup it is routed through handlers to a
customization point (often CustomIVRWorkgroupQueue.ihd), which allows you to build custom
ACD based on custom attributes, skills or other parameters that can affect ACD. This queue
type requires handler modifications. If you select custom, and do not modify the customization
point, the interaction will be redirected to the Company Operator and a warning is logged on the
Application event log.

Activate the Workgroup On the Workgroup Configuration tab, the Active check box is selected by
default. If you clear this check box, the workgroup will not receive interactions.
For a workgroup to receive interactions, it must have a queue and be active.
CAUTION

Assign users:

The Members page of the Workgroup properties allows the administrator to add or remove users
from this workgroup. The Maintain Order check box is used with the Sequential Ring Queue
Management Type to set up hunt groups.
Membership in workgroups can also be granted in the Users container.

5-14Customizing the System 2017, Interactive Intelligence, Inc.


Assign Agent Utilization:

Agents may be able to handle multiple phone calls, emails, and/or text chats simultaneously and in
any combination. Using the Agent Utilization feature, you can set how many interaction tasks an
agent can be presented at one time by using a percentage.
If the Chat category for an agent is set to 25%, it would mean that the agent could handle up to four
EXAMPLE
Chat events simultaneously. Indicating 100% for an event type would mean that the agent could
handle only one such event at a time. The percentages can vary from agent to agent based on their
experience. Agents are considered available if that the sum of the percentage utilization of all their
current interactions is less than 100.
If an agent is configured so that phone calls are set to 100 percent, chats to 25 percent, and emails
EXAMPLE
to 10 percent, then the agent could, process one phone call, or four chats, or two chats and five
emails, or one chat and seven emails, and so forth.
The Max. Assign. value allows you to further structure agent interactions. Using the previous
example, you can set agent emails to 10% so that the agent could take five emails while handling
two chats. However, you may never want the agent to handle 10 emails at one time. In that case, you
could set the Max. Assign. value to something less than 10 - we will use 6 in our example. That way
the agent will never be presented with more than six emails at any given time, even though that adds
up to just 60% utilization, but you can still achieve the total interaction values that you want.
Agent Utilization setting, set in the User Configuration, override Workgroup Utilization settings.
FOR YOUR
INFORMATION

It is recommended that you set the percent utilization for calls no lower than 51 percent.
CAUTION

5-15Customizing the System 2017, Interactive Intelligence, Inc.


CONFIGURING A USER FOR ACD SKILLS

Inherited Skills Skills can be assigned to workgroups in the Workgroup ACD configuration
screen. Any member of this workgroup automatically inherits those skills and default values for
the Proficiency and Desire to use fields. The complete set of skills assigned to each workgroup
to which the user belongs appears in this list.
Skills You can assign skills to each agent in addition to any skills inherited from the workgroups
to which the agent belongs. Agent total skill set is the union of Inherited Skills plus the agent skills
in this list. Agent inherited skills, Proficiency and Desire to use, can also be overridden.
Proficiency Type a positive whole number from 1 through 100 to assign a proficiency level for
the selected skill to this agent. The higher the number, the greater the skill level.
Desire to use Type a positive whole number from 0 through 100 to assign a Desire to use level
for the selected skill to this user. The higher the number, the greater the level of desire the agent
has to use this skill (or that the supervisor has for the agent to use the skill).

Skill names are created in the Skills container in Interaction Administrator.


FOR YOUR
INFORMATION

5-16Customizing the System 2017, Interactive Intelligence, Inc.


CONFIGURING A USER FOR ACD COST

Type a positive number from 1 to 100 to define the cost attribute for this agent. This attribute could
be a relative number to represent agent salary or some other value. By default, the Agent Score
Formula prefers agents with a high cost. If you want it to prefer agents with a low cost, change the
Weight for Agent Cost attribute in the ACD Initiate Processing step to a negative value.

CONFIGURING A USER FOR ACD CUSTOM ATTRIBUTES

5-17Customizing the System 2017, Interactive Intelligence, Inc.


Attribute 1, 2, and 3 Any unique agent attribute that can be used to qualify an agent to
receive a call. Leave this field blank if the ACD handlers do not use it. Otherwise enter any whole
number. These can be used to represent any attribute that you want to use to help the Agent
Score Formula select the correct agent for an interaction.

HANDLERS AND CUSTOM ACD

Examine the handlers involved in processing a call to a workgroup with a Queue Management Type
of Custom.
1. A call comes into the system and is handled by Interaction Attendant.
2. The caller listens to the menu and presses a key to be transferred to a Custom ACD workgroup.
3. The Interaction Attendant handler responsible for the Workgroup Transfer operation contains
a Blind Transfer step that will transfer the call to the workgroup. This generates an event called
Call to Non-System Queue which fires the System_CallOfferingNonSystemQueue handler.
4. System_CallOfferingNonSystemQueue calls the InteractionAttendantEntryPoint subroutine to
determine if this is a workgroup transfer to an ACD Queue Management type. If so, it begins the
ACD processing with the ACD Initiate Processing step. If not, as in this example, this subroutine
ends, and control returns to System_CallOfferingNonSystemQueue.
5. System_CallOfferingNonSystemQueue determines if this call should be transferred to a user
queue, workgroup queue, or station queue and calls a subroutine based upon the queue
type. In the case of Custom ACD processing, the subroutine that will handle the call is
SystemIVRCallOfferingWorkgroupQueue.
6. SystemIVRCallOfferingWorkgroupQueue checks to see if this is a call or some other type of
interaction. If it is something other than a call, it will be passed to a customization point named
SystemWorkgroupQueueInteraction where ACD processing for interactions other than calls
occurs. A call is passed to SystemIVRWorkgroupQueueAlert.
7. SystemIVRWorkgroupQueueAlert checks the queue management type for the workgroup. If it
is a Custom ACD workgroup, the call is passed into the CustomIVRWorkgroupQueue handler
where custom ACD processing begins with the ACD Initiate Processing step. Note that you
need to add the Selection step to CustomIVRWorkgroupQueue to decide which workgroup to
process. You also need to set p_bTransferred to True when the call goes to ACD processing.
Customizations required for custom ACD for interaction types, other than calls, are made in the
FOR YOUR
INFORMATION
CustomIVRWorkgroupQueueEmail, and CustomIVRWorkgroupQueueInteraction handlers.

5-18Customizing the System 2017, Interactive Intelligence, Inc.


ACD TOOLS ACD SPECIFY INTERACTION SKILL

This tool defines the requirements for a skill needed for an interaction. ACD Specify Interaction Skill
steps must precede ACD Initiate Processing steps if you are doing skills-based routing using Custom
ACD. You might also want to configure the ACD Initiate Processing step to assign the call to an
agent based on skill by increasing the values for Weight for Agent Skill and Weight for Skill.
When ACD Server evaluates a skills associated with a call, it first looks for skills that were explicitly
FOR YOUR
INFORMATION
assigned to that agent from Interaction Administrator. If the required skills were not explicitly
assigned, ACD Server looks at the skills that the agent inherited from the workgroup on which the
call currently resides. ACD Server will not consider skills inherited from other workgroups. For
example, if an agent belongs to both the Sales and Marketing workgroups, and an ACD call comes in
to the Sales workgroup, agent skills inherited from the Marketing workgroup are not considered.
Inputs Pages Both Inputs pages are used to establish the skill Proficiency and Desire to Use levels,
that are required for the interaction, and the weights of skill Proficiency and Desire to Use in
calculating the skill score.

Call Identifier The variable for the interaction for which you want to specify a required skill.
Skill Name The skill name as specified in Interaction Administrator.
Minimum Proficiency Level The minimum proficiency level required for this skill. Agents who
do not possess this minimum skill proficiency will not be eligible to receive this interaction.
Maximum Proficiency Level The maximum proficiency level required for this skill. Agents who
exceed this maximum skill proficiency will not be eligible to receive this interaction.
Weight for Proficiency Level How important Proficiency level is for this skill, as opposed to
other skills specified in other ACD Specify Interaction Skill steps. If this skill is the only skill you
are specifying, then leave the default value in this parameter. If you are more concerned with
this skill, then weight this parameter more heavily than Weight for Proficiency Level in other
ACD Specify Interaction Skill steps in this handler.
5-19Customizing the System 2017, Interactive Intelligence, Inc.
Minimum Desire to Use Level The minimum Desire to Use level required for this skill. Agents
who do not meet the minimum Desire to Use level specified here will not be eligible to receive
this interaction.
Maximum Desire to Use Level The maximum Desire to Use level required for this skill.
Agents who exceed the maximum Desire to Use level specified here will not be eligible to
receive this interaction.
Weight for Desire to Use How important Desire to Use level for this skill is, as opposed to
other skills specified in other ACD Specify Interaction Skill steps. If this skill is the only skill you
are specifying, then leave the default value in this parameter. If you are more concerned with
this skill, then weight this parameter more heavily than Weight for Desire to Use in other ACD
Specify Interaction Skill steps in this handler.

ACD TOOLS ACD INITIATE PROCESSING


This tool starts the ACD processing for an interaction. This tool should be called when an interaction
is on a Workgroup queue. This tool generates an ACDProcessQueueItem event that starts the
ACDAvailableInteraction handler. In this tool you specify the weights used to calculate agent score,
interaction score, and other values used in ACD processing.

Inputs Page The first Inputs page contains parameters which affect the Agent Score.

Call Identifier The identifier of the interaction on which ACD processing is performed.

5-20Customizing the System 2017, Interactive Intelligence, Inc.


Weight for Agent Skill The level of importance for Agent Skill in the Agent Score formula.
Agent skill levels are assigned in Interaction Administrator on a User or Workgroup level.
Specify the skill requirements for a call using one or more ACDSpecifyInteractionSkill steps
before this ACDInitiateProcessing step. If Agent Skill is more important for you than Agent Cost,
Agent Available Time, or some other custom attribute, weight this parameter more than the
other parameters.
Weight for Agent Cost The level of importance for Agent Cost in the Agent Score formula.
Agent Cost is an attribute assigned to an agent in Interaction Administrator. Use a positive value
in this parameter to assign the call to the agent with the highest cost. Use a negative value in this
parameter to assign the call to the agent with the lowest cost.
Weight for Agent Available Time The level of importance for Agent Available Time in the Agent
Score formula. If you want to assign this call to the agent who has been off the phone the longest,
weight this parameter more heavily than Weight for Agent Skill and Weight for Agent Cost.
Weight for Agent Attribute 1 Weight to be used for Agent Attribute 1. This attribute can be
assigned in Interaction Administrator.
Weight for Agent Attribute 2 Weight to be used for Agent Attribute 2. This attribute can be
assigned in Interaction Administrator.
Weight for Agent Attribute 3 Weight to be used for Agent Attribute 3. This attribute can be
assigned in Interaction Administrator.
Agent Available Time Interval The amount of time (in seconds) before increasing the Agent
Available Time value by one. The longer an agent is available, the higher their Agent score will be.

Inputs Page The second Inputs page contains parameters which affect the Interaction Score.

Weight for Skills If you are concerned with matching calls to agents with the best skill for that call,
then increase the Weight for Skills more than the weights for Priority, or Time in Queue or System.
Weight for Priority If you want calls with the highest priority to be answered first, then
increase the Weight for Priority more than the weights for Skills, or Time in Queue or System.

5-21Customizing the System 2017, Interactive Intelligence, Inc.


Weight for Time in Queue If you want calls that have been holding in this queue the longest to
be answered first, then increase the Weight for Time in Queue more than the weights for Skills,
Priority, or Time in System.
Weight for Time in System If you want calls that have been connected to Interaction Center
the longest to be answered first, then increase the Weight for Time in System more than the
weights for Skills, Priority, or Time in Queue.
Priority Level The priority level assigned to this call. If you want priority taken into account
when calculating interaction scores, you should also increase the value in the Weight for
Priority parameter.
In-Queue Time Interval The number of seconds before the Time in Queue value is increased
by one. This increases a calls score and the likelihood that it will be assigned to an agent.
In-Queue Time Limit The number of seconds before the ACD Queue Item Timeout event is
generated. The ACD Call Timeout initiator is configured to start a handler when a call reaches
its In-Queue time limit. Think of this parameter as the amount of time to wait before special
processing is performed on the call by the AcdQueueItemTimeout handler.
In-System Time Interval The amount of time (in seconds) before increasing the Time in System
value by one. This increases a calls score and the likelihood that it will be assigned to an agent.

Outputs Page:

Call Identifier The variable for the interaction flagged for ACD processing.

HOW ACD SCORES ARE CALCULATED


You can configure both the agent score formula and the interaction score formula to match agents
to interactions and interactions to agents according to your needs. Both formulas are configured in
handlers within the ACD Initiate Processing tool.
But first, the agent skill level must be determined in an ACD Specify Interaction Skill step.

5-22Customizing the System 2017, Interactive Intelligence, Inc.


Agent Skill Level Agents are assigned skills in the Interaction Administrator. For example, imagine
that you manage a call center that answers DOS and UNIX questions. Some of your agents are DOS
experts, and some are UNIX experts. Each agent has both a DOS skill and a UNIX skill. To ensure that
agents receive calls they are best qualified to answer, you would assign DOS experts a high DOS skill
proficiency level, and UNIX experts a high UNIX skill proficiency level.
Once you have assigned skills, modify the CustomIVRWorkgroupQueue handler (or the appropriate
customization point for the type of interaction) to assign skill requirements to an interaction with
ACD Specify Interaction Skill steps. The handler (using a callers input, evaluating the number dialed,
or any other method) decides whether the call requires a DOS or UNIX skill and the minimum skill
proficiency required. Only agents whose skill proficiencies meet the interactions minimum skill
requirements are considered as potential recipients.
Agent skill level is determined by the following formula:
Agent Skill Level =
[(Agents Proficiency Value * Weight for Proficiency) +
(Agents Desire to use value * Weight for Desire to use)] /
Absolute value of the sum of the Weight for Proficiency and Weight for Desire
to use
An Agent has a Skill Proficiency of 70 and a Desire to use of 100. The weight for that skills
EXAMPLE
proficiency is set to 2, and the weight for Desire to use is 1. The calculation to determine the agents
skill level would be:
Agent Skill Level = [(70 * 2) + (100 * 1)] / |2 + 1|
So, in this case, the agents skill level is 80.
Agent Score When more than one agent is available to pick up an interaction from an ACD queue,
the agent with the highest score is selected. Your configuration determines how agent scores are
calculated. You might set up your formula so that higher scores are given to agents who have low
cost, better skills, or have been off the telephone the longest. You can even configure your formula
to take two, or even all three of these factors into consideration. The formula used to calculate the
agents score is shown below:
Agent Score =
(Agent Cost * Weight for Agent Cost) +
(Agent Available Time * Weight for Agent Available Time) + (Agent Skill Level *
Weight for Agent Skill Level) +
(Agent Attribute 1 Value * Weight for Attribute 1) + (Agent Attribute 2 Value *
Weight for Attribute 2) + (Agent Attribute 3 Value * Weight for Attribute 3)
You can configure how agent scores are calculated by adjusting the weights associated with
each element.
Except for Agent Cost, you will not usually assign negative weights. For example, if you set a Weight
CAUTION
for Agent Skill level to a negative number, then calls will not be assigned to the most qualified agents.
Interaction Score When there is more than one interaction waiting to be answered and an agent
becomes available, the interaction with the highest score is selected. The formula used to calculate an
interaction score is shown below:
Interaction Score =
(Agents Skill Score * Weight for Skills) + (Priority * Weight for Priority) +
(Time in Queue * Weight for Time in Queue) + (Time in System * Weight for Time
in System)

5-23Customizing the System 2017, Interactive Intelligence, Inc.


The Agent Skill Level and Interaction Skill Level will not be factored in unless the skill is specified
FOR YOUR
INFORMATION
using an ACD Specify Interaction Skill step.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following lab in your lab manual:
Lab 21: Building a Custom ACD Queue

5-24Customizing the System 2017, Interactive Intelligence, Inc.


5.3 Database Tools

DATABASE TOOLS

The Database tools allow handlers and subroutines to read from and update databases. With
database tools, you can:
Look up customer account numbers and retrieve their balance and then play the balance back to
them using TTS.
Accept input from the Telephony User Interface (TUI) to update a field in a database table, such
as the date and time that they will arrive to pick up an order.
Look up a password that has been input from the TUI so that a caller can gain access to information.
Look up information to populate fields on a webpage with personalized information.
Update customer information based upon input from a webpage.
Perform many other database-related tasks.

5-25Customizing the System 2017, Interactive Intelligence, Inc.


DATABASE PROCESS
Typically, the Database tools are used in the following order within a handler, as illustrated by this
diagram. Use this multi-step process as a guide when creating database functionality within a handler.

1. DB Open to open an ODBC data source.


DB Open is used to specify the data source name, username, password, name of the variable to
hold the connection handle, and the maximum number of connections.
2. DB Get Connection to establish a connection with the database.
DB Get Connection attempts to open the actual connection. Once the connection is established,
DB Query, DB Fetch, and DB SQL Exec can perform operations on the database.
3. DB Query to find records or the DB SQL Exec to perform operations other than a query on
the database.
With a connection established, DB Query can execute a SELECT statement to create a result set,
preparing the records for a DB Fetch step. Each connection can only store one result set, so if
you need to retrieve multiple result sets for multiple fetches, you should use additional DB Get
Connection steps and associated DB Query steps.
4. DB Fetch accesses the result set.
DB Fetch retrieves a record from the result set. The values retrieved are stored in the variables
set up in the DB Query step. If you want to retrieve multiple records from a result set, loop back
through the DB Fetch. It will take the Failure exit path when there are no more records in the
result set.
5. DB Release Connection
If the handler no longer needs to access the database, use a DB Release Connection to drop the
connection to the database. If you opened multiple connections, you can use this step to close any
connections that you do not need. Always release any open connections before exiting a handler.
6. DB Close
When the handler finishes running, close the ODBC data source with a DB Close step.

5-26Customizing the System 2017, Interactive Intelligence, Inc.


SUPPORTED DATABASES
Interactive Intelligence currently supports the following databases for Interaction Center for
report logging:
Microsoft SQL 2008 R2 SP2 (64 bit)
Oracle 11g R2 (64 bit)

Beyond these databases, Interactive Intelligence should be able to communicate with any ODBC-
compliant database through the Database Tools, but such a connection is not guaranteed, nor will
Support agents necessarily be able to troubleshoot problems connecting to other databases.
Always check testlab.inin.com for the latest information regarding supported databases.
FOR YOUR
INFORMATION

DB OPEN
The DB Open tool opens an ODBC data source and passes along parameters like username and
password needed to access the data source. This step is usually followed by a DB Get Connection step.

Settings Page:
Data Source Specifies the previously created ODBC data source through which you want to connect.
User Name Type the database username which has the permissions needed to open the database.
Password Type the password for the database user.
Database Variable Name This is the name (handle) for the database you are opening.
Maximum Database Connections The number of connections this handler will open. If you are
going to be requesting multiple results from the query, you can specify more connections. Multiple
connections allow you to query the database, leave the result on the server, perform another query,
and go back later to continue getting records. It is recommended that you leave this setting at 1.
5-27Customizing the System 2017, Interactive Intelligence, Inc.
Exit Paths:
Success If this step executes successfully, it takes the Success exit path.
Failure If this step does not execute successfully, it takes the Failure exit path. This can occur when
the ODBC data source is not valid, the user name or password are incorrect, the step times out
before the DB can be opened, or the DB server is not available.

DB GET CONNECTION
The DB Get Connection tool opens up a connection to a database specified in DB Open. If you are
planning to use a DB Query step to retrieve a result set, keep in mind that each connection can
only hold one result set. If you want to retrieve more than one result set, get a connection for each
result set you want to retrieve. See the DB Query step for more information on result sets. This step
should always be preceded by a DB Open step.

Settings Page:
Database Variable Specifies which database to open. For this parameter, enter the database
variable created in a DB Open step.
Database Connection Variable Names the database connection.
Timeout Specifies how long this step will wait for a connection with the server before exiting
Failure. The default for this value is 60 seconds. Entering a value less than or equal to 0 results in this
step using the default value of 60 seconds. This parameter takes a numeric value, so you can specify a
decimal, such as 2.5.
Exit Paths:
Success If this step executes successfully, it takes the Success exit path.
Failure If this step does not execute successfully, it step takes the Failure exit path. This can occur
when the DB variable or DB connection variable is not valid, if the step times out before the
connection could be performed, or the DB servers connection limit has been reached. Failures on
open and connect depend on the type of database (Oracle, Sybase, and so on).
5-28Customizing the System 2017, Interactive Intelligence, Inc.
DB QUERY
The DB Query tool retrieves a result set from a table based on a Where clause. The result set
retrieved matches the conditions specified in the Where clause. You can then specify a variable
(bind) for each row of data returned.
Following is one example of a where clause, and the DB Query step to execute that where clause

Sample Where Clause:


The sample database contains transaction IDs, the names of the agents who processed the
transactions, agent phone number, and the cost of the transaction. You want to retrieve all
purchase records for a single agent. In this example, the agents name is specified in a variable
called strAgent1. The Clothing database to be queried is shown below.

ID Name Phone Cost

123 Bart 555-1234 $5.00

124 Bart 555-1234 $50.00

125 Lisa 555-9876 $10.00

126 Bart 555-1234 $15.00

127 Lisa 555-9876 $5.00

Empty Empty Empty Empty

The Select statement used to retrieve the value is: SELECT ID, Cost FROM Clothing WHERE
Name=strAgent1.

5-29Customizing the System 2017, Interactive Intelligence, Inc.


Creating the Where Clause with the DB Query Tool:
The following explains how to configure the DB Query tool to execute this Select statement.
1. Specify the Connection Variable and Data Source.
The Connection Variable is generated by the DB Connect step elsewhere in the handler. The
Data Source list is populated with ODBC data sources you have configured.
2. Select a Table Name.
Once you have selected a data source, the Table Columns for that data source are listed as
choices for this parameters. Using the sample database as an example, Clothing is the table
listed. The Table Name forms the FROM portion of your Select statement, so you have now
configured FROM Clothing.
Once you have selected a Table Name, the columns within that table appear in the Table Columns List.
3. In the Table Columns list, select the columns you want to query.
When you choose Clothing as your Table Name, ID, Name, Phone, and Cost all appear in the
Table Column list. You would select ID, then click the Bind button. In the Column Binding Dialog,
you would select the variable which will receive the value retrieved from the ID column. Next
you would select the Cost table column and bind the variable that will receive the value from the
Cost Column. (The variable to which the Table Columns are bound are created with Assignment
steps that precede this DB Query step or in the Variables palette.) Binding variables to the
ID and Cost columns completes the SELECT portion of your Select statement. Now you have
configured DB Query to execute the following statement: SELECT ID, Cost FROM Clothing
The next step will be to add the WHERE portion of the Select statement.
4. Specify the Where Clause Variable.
In the Where Clause Variable parameter, you will specify the variable that contains your Where
clause. Create a Where clause in an Assignment step preceding this DB Query step.
The DB Query step will insert the WHERE portion for you, so your Assignment step only needs
to assign: Name = strAgent1.
To type this value in Expression Editor Assistant, you would type the following: Name= &
SQLStr(strAgent1).
When the handler executes, this expression results in Name = strAgent1. Once you have
assigned this value to a string variable, you can select that variable from the DB Querys Where
Clause Variable drop-down list.
Once you have selected the Where Clause Variable, the WHERE portion of the Select statement
is complete. When you run the handler, the following Select statement is executed: SELECT ID,
Cost FROM Clothing WHERE Name=strAgent1.
5. After this step executes, you can use a DB Fetch step to retrieve, one record at a time, the
records stored in the result set. This example is continued in the documentation for that tool.
Settings Page:
Connection Variable Specifies on what connection to perform the query. Use a connection
variable that you specified in a DB Get Connection step. Each connection can contain only one
result set, so if you need more than one result set, open more than one connection.
Data Source Select a data source to query. The table columns from the selected data source appear
in the Table Name drop-down list box.
Table Name This is a list of tables available for the data source you specified in the previous Data
Source parameter. When you select a Table Name, the columns defined in that table appear in the
TableColumns/VariableList.
Runtime Table Name Specify a string expression that, at handler runtime, is used as the table
name for the select statement. This field is optional. If no value is specified, the table selected in the
Table Name field will be used.
Table Columns/Variable List This is a list of Columns for the table specified in the previous
Table Name parameter. You can bind variables created previously in Assignment steps or in the
Variables palette.
5-30Customizing the System 2017, Interactive Intelligence, Inc.
Binding button A binding specifies which variable receives the value of the selected column and
row. Use this button to bind a column to a variable. When you execute this query and do a fetch,
that variable receives the value of that column for the current row. A second fetch overwrites the
value of this variable.
Users wanting to bind a variable to a column are presented with the list of variables that are eligible
for binding to the SQL type for that column.
The bindings dialog box allows bindings to convertible types. This is useful if you want to read a
FOR YOUR
INFORMATION
value from a column and have it be converted into another type automatically. For instance, SQL
integers into numeric type variables.
Where Clause Variable Specify the variable that contains a Where clause. You will need to
construct the Where clause in an Assignment step preceding this step.
Exit Paths:
Success If this step executes successfully, it takes the Success exit path.
Failure If this step does not execute successfully, it takes the Failure exit path. This can occur when
information specified about the table or view is incorrect, the DB connection variable is not valid, or
the Where clause was not correct (that is it did not contain a valid SQL statement).

DB FETCH
DB Fetch retrieves a record from a result set generated in a DB Query step.

5-31Customizing the System 2017, Interactive Intelligence, Inc.


For example, the following result set is generated from a DB Query step.

ID Name Phone Cost

123 Bart 555-1234 $5.00

124 Bart 555-1234 $50.00

125 Lisa 555-9876 $10.00

126 Bart 555-1234 $15.00

127 Lisa 555-9876 $5.00

Empty Empty Empty Empty

The first time the DB Fetch step executes, it retrieves record with ID 123, and takes the success
exit path. You can then pull values from any variables bound to the column values, as specified in
the DB Query step. Then the handler would be designed to loop around and execute this DB Fetch
step again. DB Fetch automatically retrieves the value of the next record, number 124. Each time
the DB Fetch step executes, it retrieves the next value. When it reaches the empty record, the DB
Fetch step fails and the loop ends.
In this example, you could write each value to a list of string for insertion into a webpage or some
other operation.
Settings Page:
Database Connection Variable The name of a variable you created in a DB Get Connection step.
Exit Paths:
Success If this step executes successfully, it takes the Success exit path.
Failure If this step does not execute successfully, it takes the Failure exit path. This can occur when
the parameters set in the DB Query step were invalid, the DB Connection Variable is invalid, if the
step times out before the fetch could be performed, or if there are no more rows to fetch from the
result set. If there were no more rows to fetch from the result set, this means either a) the fetch
cycle is now complete, or b) there was no successful query performed before the fetch (this means
that for this step, the handler author cannot tell the difference between a true failure [like a lost
DB connection] and a simple you are at the end of the result set indication.)

DB RELEASE CONNECTION
DB Release Connection releases a connection to the database server, freeing up the server for
another connection. This step is usually followed by a DB Close step.
You may not want to follow this step with a DB Close in cases where you have opened multiple
connections to the same data source. This is useful in cases where you want to perform nested
queries against the database.
For instance, suppose you execute a query step, then fetch a record, and then perform an additional
query (based on some data in that fetched record) in order to process the record. If you perform
that second query on the same connection, your first result set will be lost (the server keeps one
current result set for each connection). So, you open another connection (or use another one that
was opened before) and perform the second query on that query. Then you fetch the result from
that second query and finish whatever processing you needed to do for the original record. Now you
can go back and fetch the second record from the first query. To process the second record you will
probably do the same thing you did for the firstdo another query and fetch, then finish processing.

5-32Customizing the System 2017, Interactive Intelligence, Inc.


After you have finished processing all the records from your original query, you are left with two
open connections. If only one connection is needed for the rest of your handler, then you can release
the second one.

Settings Page:
Database Variable Specifies the database variable for the connection to release.
Exit Paths:
Success If this step executes successfully, it takes the Success exit path.
Failure If this step does not execute successfully, it takes the Failure exit path. This can occur when
the DB Connection Variable is not valid.

5-33Customizing the System 2017, Interactive Intelligence, Inc.


DB CLOSE
DB Close closes an ODBC data source previously opened by a DB Open step.

Settings Page:
Database Variable Specifies which database variable to close.
Exit Paths:
Success If this step executes successfully, it takes the Success exit path.
Failure If this step does not execute successfully, it takes the Failure exit path. This can occur when
the Database Variable is invalid.

DB SQL EXEC
This tool is useful when you want to do something with a database other than query. DB SQL Exec can
be used to insert data into a database, update a row already in a database, delete data from a database,
or run a stored procedure on the server (scripts stored on the database that operate on the data
tables). You can use this tool to create a temporary table, then run a DB Query against that table to
return data, allowing you to work around the DB Query limitation of querying from a single table.
To use this tool, build a SQL statement using one or more Assignment steps, and pass it in as a string
variable. Use this string variable as your SQL Statement Variable on the Settings page. You can use
the & (string append) function in several Assignment steps to build complex SQL statements.

5-34Customizing the System 2017, Interactive Intelligence, Inc.


Settings Page:
Database Connection The name of the variable you created in a DB Get Connection step.
SQL Statement Variable The name of the variable that contains the SQL statement. The value of this
variable is created with one or more Assignment steps. Following are some sample SQL Exec statements:
SQLExec statement:
EXAMPLE

INSERT INTO CUSTOMER_TABLE (CUSTOMER_ID, CUSTOMER_NAME, CITY, STATE)


VALUES (ACB8934,
Joes Bar & Grill, Indianapolis, IN)
Assign String using variables:
EXAMPLE

INSERT INTO CUSTOMER_TABLE (CUSTOMER_ID,


CUSTOMER_NAME, CITY, STATE) VALUES ( &
SQLStr(sCustomerID) & , & SQLStr(sCustomerName) & , &
SQLStr(sCity) & , & SQLStr(sState) & )
Exit Paths:
Success If this step executes successfully, it takes the Success exit path.
Failure If this step does not execute successfully, it takes the Failure exit path. This can occur when
the DB connection variable is not valid or the SQL statement is not valid.

5-35Customizing the System 2017, Interactive Intelligence, Inc.


DB SQL EXEC2

This tool allows for the execution of any SQL statement that does not return a result set. If used for
queries or stored procedure calls that return result sets, you will not be able to retrieve the results.
Use DB Query and DB Stored Procedure for stored procedure calls that return result sets instead of
this tool.
This tool will optionally allow for the retrieval of the number of affected rows (INSERTs, UPDATEs,
and DELETEs only).
Like the DB list tools, this tool will grab a connection from the cache (or create one if one is not
available), perform the operation, then release the connection back to the cache. In other words, it
is self-contained, which means you do not need to call DB Open & DB Get Connection prior to using
this tool. However, a Data Source must be created in Interaction Administrator.
Inputs Page:
IC Data Source The name of the IC (not ODBC) data source to use.
SQL Command The SQL command to execute.
Timeout (seconds) The time, in seconds, before this tool will return with a timeout error. Where
supported by the RDBMS, the statement/query timeout on the server will also be set with this value.

5-36Customizing the System 2017, Interactive Intelligence, Inc.


Check Count of Affected Rows If TRUE, a call will be made to retrieve the count of the number of
rows affected by this command. If you know the command does not affect any rows or produce a row
count (or you do not care about the row count), set this to FALSE as an optimization.
Outputs Page:
Affected Row Count If the input Check Count of Affected Rows is TRUE, this will contain the
row count; note that a row count of zero is possible in many situations (for example the where
clause of an UPDATE does not specify any rows, the command does not produce a row count, and
so on). If Check Count of Affected Rows is FALSE, or an error was encountered, this value will be
set to -1.
Error Code If the tool execution was successful, this will be set to zero; otherwise, it will be set to
the native (RDBMS) error code, or in the case of an internal error (for example Notifier error) it will
be set to an IC-specific error code.
Exit Paths:
Success The operation was successful. This does not mean that there were affected rows; it only
means the SQL statement itself did not generate any errors.
No Rows This path will only be taken if all three of the following conditions are met:
There were no errors,
The input Check Count of Affected Rows is TRUE, and
The result did not affect any rows (or did not produce a row count).

Failure There was a SQL or internal error generated while trying to execute this command. Check
the IPDBServer.log for information on the error.

STORED PROCEDURES
With the database tools that we have discussed so far, a handler can query a single database table,
update or write a record to a table, or delete a record from a table. To perform more advanced
database functions in handlers, such as joins, table creation, use stored procedures.
A stored procedure is a function or script that is saved on a database server. This script can be
executed on the database server at the request of a database client. Stored procedures can receive
input from the client at the time they are executed. Stored procedures carry out their processing
on the server and can return data/results of that processing to the client. Database administrators
use stored procedures to carry out complex functions that are best performed on the server (as
opposed to the client). In addition, stored procedures often outperform normally submitted SQL
because the SQL in the procedure is pre-parsed, and execution plans pre-generated.
A definition of a stored procedure specifies parameters, the result set, and the return value.
A stored procedure parameter is similar to the standard programming concept of a function
parameter. These parameters can be input data, meaning the value passed in is used during
processing. They can also be output data, meaning the reference to a value will be filled in during
processing. They can also be both, meaning their initial value will be used during processing, and
that value may then be changed before processing completes.

5-37Customizing the System 2017, Interactive Intelligence, Inc.


Stored Procedures are created on the databases server:

The creation of stored procedures is a role of the Database Administrator and is beyond the scope
FOR YOUR
INFORMATION
of this class.
In Interaction Designer, under the Utilities menu, is a menu option for Stored Procedures. Selecting
the Stored Procedures options opens the DB Stored Procedures Definitions dialog that displays and
allows you to edit the definition of a stored procedure. This is either the definition as passed in by
the ODBC driver, or the definition that you have modified previously in this dialog box.

Use this dialog to augment a stored procedure definition if the ODBC driver did not pass in a
complete definition. ODBC drivers differ in the amount of information that they pass to Interaction
Designer. Some will pass all input and output parameters, some will not. Use this dialog if you realize
that your ODBC driver is passing an incomplete definition.

5-38Customizing the System 2017, Interactive Intelligence, Inc.


The definition that you create here is stored on the IC server. When you select this definition in a
FOR YOUR
INFORMATION
DB Stored Procedure step and then save that handler document, the definition will also be stored
within the handler. It is possible that the definition stored on the IC server will become different
from the definition stored with the handler. This situation can occur if you make a change to the
stored procedure itself on the database server, and then only update the copy on the IC server
or the copy in the handler. If you open a handler and Interaction Designer detects that there is a
difference in the definition in the handler and the definition on the IC server, you will be presented
with a dialog asking you to select the current definition (the one you want to keep).
The fields in the DB Stored Procedure Definitions are defined below:
DSN The name of the data source on which the procedure was created. The concept of the
catalog varies from one RDBMS vendor to the next. It usually corresponds to the physical database,
but there are exceptions. For example, with dBase and FoxPro it usually corresponds to the directory
in which the data files reside. IC assumes that the catalog is tied to the ODBC DSN. So, if access to
multiple catalogs is required, create and configure multiple ODBC DSNs.
Schema The schema in which the stored procedure resides. The schema is the official ANSI term
for what used to be commonly known as the qualifier. It is usually the creator/owner of the
database object. Worth noting is that Sybase and Microsoft SQL Server have a special schema name
that is used when the owner of the object is also the database owner: dbo.
Stored Procedure The name of the stored procedure as it is stored on the DB server. You cannot
change the name of the stored procedure from this field.
Parameters After you have specified a stored procedure in the previous parameter, this list is
populated with any parameters passed in by the ODBC driver, and any parameters that you have
previously added to this definition. Add or edit parameters in this list as necessary. Adding or
editing a parameter does not change the actual stored procedure (on the database server), only the
Interaction Designer definition of it. Any change to the actual procedure must be performed on the
database server where the stored procedure resides.
Result Columns After you have specified a stored procedure, this list is populated with any result
columns passed in by the ODBC driver.
Return Value Type A value returned as a result of the processing performed by the stored
procedure. The type of value returned depends on the RDBMS. For example, Oracle and DB2 allow
you to return most legal SQL data types (LONG or BLOB types usually being the exceptions), but
Sybase and Microsoft SQL Server both limit return types to INTEGERs.
Return Value Type Size The amount of memory to reserve for the returned value. This field will
only be enabled for SQL Types that do not have fixed size.
Return Value Type Decimal Digits For values that are SQL Float type, this specifies the number of
digits to store. This is applicable only to Decimal and Numeric types.

DB STORED PROCEDURE TOOL

5-39Customizing the System 2017, Interactive Intelligence, Inc.


This tool calls a stored procedure that is stored on the database server. The tool properties allow
you to bind handler variables/expressions to the stored procedure parameters, result columns, and
return value. Depending on which database server product you are using, the output parameter
values and the return value will either be populated:
Immediately on the call to DB Stored Procedure, or
If a result set is returned, output parameters and return value will not be set until all rows have
been fetched. This is for all databases.

Consult with your database administrator to determine the behavior of your particular database server.
Parameters tab:

DB Connection The variable containing the database connection generated by the DB Get
Connection tool.
DSN (Catalog =) The name of the data source on which the procedure was created. The concept of the
catalog varies from one RDBMS vendor to the next. It usually corresponds to the physical database,
but there are exceptions. For example, with dBase and FoxPro it usually corresponds to the directory
in which the data files reside. IC assumes that the catalog is tied to the ODBC DSN. If access to multiple
catalogs is required, create and configure multiple ODBC DSNs.
Schema The schema in which the stored procedure resides. The schema is the official ANSI term
for what used to be commonly known as the qualifier. It is usually the creator/owner of the database
object. Worth noting is that Sybase and Microsoft SQL Server have a special schema name that is
used when the owner of the object is also the database owner: dbo.
Stored Procedure The name of the stored procedure as it is stored on the DB server.
You cannot change the actual name as it is defined on the DB server from this field.
FOR YOUR
INFORMATION

Runtime Stored Procedure An optional expression that results in a string that names a stored
procedure. This allows you to run a stored procedure dynamically from a handler. If you specify a
value here, the value in the Stored Procedure parameter is ignored.

5-40Customizing the System 2017, Interactive Intelligence, Inc.


If specifying a value here, you are responsible for including any required schema prefix. For
FOR YOUR
INFORMATION
example, if the stored procedure is called MyProc, and it is owned by user Fred who is not the
database owner (dbo), and the connection was created under a user other than Fred, then you
would need to provide Fred.MyProc as the value here. As another example, if Fred was the dbo,
then you could supply either dbo.MyProc or just MyProc, since Sybase and Microsoft SQL server
will automatically attempt to resolve any unqualified object name with dbo. As a final example, if
the database connection was created using Freds account, then either Fred.MyProc or MyProc
will work.
Execution String This is optional. Any executable SQL statement can be provided. If the statement
contains embedded parameter markers (?), they will be bound to the corresponding bind parameters
that are specified (it is up to the user to make sure the number of parameter markers matches the
number of bound parameters, and that the ordinal positions are correct). The intent is to allow a way
to provide the RDBMS-specific stored procedure call syntax when the ODBC driver does not support
the ODBC escape syntax for stored procedure execution. Fortunately, since most drivers support the
escape syntax, you should not typically need to provide anything here.
Although not originally intended as a feature, the execution string can be any valid SQL statement
FOR YOUR
INFORMATION
it is not limited to a stored procedure call. For example, you could use it to perform a SELECT
Count(*). You can pass input parameters and also get a result set; however, you cannot set output
parameters or get a procedure return (since there is no procedure).
Parameters list The parameters for the specified stored procedure. You can bind variables to the
input and input/output parameters. If you do not see all of the parameters that should be listed,
the ODBC driver may not be passing all of the parameters to this tool. In this case, you may need to
define these parameters in the DB Stored Procedure Definition dialog (which you can open through
the Utilities menu).
In some cases, you may have to take a couple of extra steps to convert values in a handler to
FOR YOUR
INFORMATION
parameters in the stored procedure. For example, you have a SMALLINT data type as an input
parameter that is basically acting as a Boolean (that is it will either hold a 1 or a 0). When you open
the expression editor to supply a value, the expression editor only displays the primary mapping
type for SMALLINT, which is an IC integer. This is because the expression editor is designed with the
notion that everything is about the current (single) data type. Unlike Interaction Designer, it has no
way of presenting a list of both Boolean and integer variables. To work around this problem, define
an integer variable to use, then set it with the Boolean value using one of the expression editors
type conversions.
Bind Click the Bind button to bind the selected parameter to a variable (for in/out and out
parameters) or expression (for input parameters).
Unbind Click the Unbind button to unbind a parameter from a variable or expression.
Clear Bindings Click Clear Bindings to remove all bindings to all parameters.
Stored Procedure Return Value A value returned as a result of the processing performed by the
stored procedure. The type of value returned depends on the RDBMS. For example, Oracle and DB2
allow you to return most legal SQL data types (LONG or BLOB types usually being the exceptions),
but Sybase and Microsoft SQL Server both limit return types to INTEGERs.

5-41Customizing the System 2017, Interactive Intelligence, Inc.


Result Set tab:

This list is populated if the stored procedure fetches any data. You can bind variables to the fetched
data. If you do not see all of the column names that should be listed, the ODBC driver may not be
passing all of the column names to this tool. In this case, you may need to define these column names
and other result set properties in the DB Stored Procedure Definition dialog (which you can open
through the Utilities menu).
IC does not currently support retrieving multiple result sets. If the stored procedure generates
CAUTION
multiple result sets, then only the first result set can be retrieved.
Name The name of the column from which the data is fetched.
Position The ordinal position of the column in the result set, starting from 1.
Expression The variable to which the fetched data is bound. You can specify only a variable, not
an expression.
Bind Click the Bind button to bind the selected column to a variable.
Unbind Click the Unbind button to unbind a variable from a column.
Clear Bindings Click Clear Bindings to remove all bindings to all columns.
Exit Paths:
Success This step takes the Success exit path if the stored procedure is executed.
Failure This step takes the Failure exit path if it is not able to run the stored procedure. Probable
causes include:
Stored procedure not found. Usually this is due to a wrong or missing schema qualifier, or
insufficient permissions.
Insufficient execution permissions.
Data type mismatch with one of the procedure parameters or return value.

The best way to troubleshoot the cause of a failure is to examine the IPDBServer.ininlog fileit will
typically contain a useful RDBMS error message.

5-42Customizing the System 2017, Interactive Intelligence, Inc.


Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following lab in your lab manual:
Lab 22: Communicating with a Database

5-43Customizing the System 2017, Interactive Intelligence, Inc.


5.4 Prompt Libraries

WORKING WITH PROMPT LIBRARIES


Prompt Libraries are handlers that were created specifically to hold prompts and strings. All of the
prompts, prompt phrases, text strings, and sequence strings that are released with IC are stored in
the handlers listed below.
ALL prompts and strings should be stored in these handlers. The Assemble Prompt Phrase, Assemble
Text Phrase, and Play Prompt Phrase tools are used within other handlers to build and play prompts
or strings from these libraries.

5-44Customizing the System 2017, Interactive Intelligence, Inc.


RECORDING PROMPTS

You can have prompts professionally recorded and import them into the appropriate prompt
library, or you can record them using a high-quality noise-canceling headset attached to IC. Before
recording, verify that the prompts will be saved in the correct format by opening the recording
software, such as Microsoft Sound Recorder, and checking the properties. Set prompts to CCITT
u-law, 8-kHz, 8-bit, mono.
Follow these steps to record a new prompt:
Open the prompt handler in which the new prompt will be stored.
Open the Play Prompt step.
Click the Edit button on the Inputs page of the Play Prompt step. This opens the Prompt Editor.

Click the Insert button to open the Prompt dialog.

The Trim Leading Silence check box allows you to remove any silent moments at the beginning of a
new prompt. When you click the Stop button to end recording of a new prompt, the trim is applied.
You cannot trim silence from a prompt created in a previous recording session. The Trim Trailing
Silence option performs the same function at the end of a new prompt.

5-45Customizing the System 2017, Interactive Intelligence, Inc.


Type a name and description for the new prompt and click OK. This is the name you will specify
when playing back the prompt with a Play Prompt Phrase step. The Chat Text field is the
text that will appear in a chat interaction. The TTY Text field is the text that will appear on a
TDD(Telephone Device for the Deaf) device.

Click the Record button.


Read the prompt script.
Stop the recording by clicking the Stop button.

The prompt and its duration are displayed in the Prompt Name list. The Prompt is played back
automatically when the recording is finished.
Because there is no select button in the Prompt Editor, the prompt that is selected when you click
click OK is the prompt that appears on the Inputs page.
If the audio quality is inferior, check the Multimedia properties in Control Panel to make sure the
FOR YOUR
INFORMATION
Microsoft CCITT G.711 Audio codec is installed.
An alternative way to record prompts is to record the prompt in Interaction Attendant or to set your
status to an unavailable status and record the prompt as a voice mail. The .wav file that is produced
will be in the proper format and can then be imported into your prompt libraries. We will be using
this method in an upcoming lab.

5-46Customizing the System 2017, Interactive Intelligence, Inc.


PROMPT TOOLS ASSEMBLE PROMPT PHRASE

The Assemble Prompt Phrase tool is used to define a sequence of prompt strings that will form the
structure of a single prompt. The sequence can consist of string variables or literals that can be read
using Text-to-Speech (TTS), text files, and existing prompts.
The Assemble Prompt Phrase tool only builds prompt phrasesit does not play them. The Play
FOR YOUR
INFORMATION
Prompt Phrase tool is used to play prompts.
For example, the phrase used in the default Dial-by-Name functionality that states, Please enter the
first four characters of your partys last name is made up of three strings: A prompt that says, Please
enter the first, a string variable which value is determined by a setting in Interaction Attendant, and a
prompt that says, characters of your partys last name.
The following shows the tabs for the Assemble Prompt Phrase step that is used to build the phrase.
General Contains the Label and Notes for the step. It is a good idea to enter the string that is being
assembled by this step into the notes field.

5-47Customizing the System 2017, Interactive Intelligence, Inc.


Input The Input tab has the following properties:

Call Identifier The identifier for the call on which the prompt phrase is assembled. The tool
uses the identifier to ascertain the language of the call.
Language The language code of the prompt phrase to be played. If no language is specified,
the language attribute of the call will be used. If no language is specified for the call either, the
default language will be used.
Singular if true This Boolean value permits simple handler-based control over the common
case of generating different prompt sequences for plural arguments than for singular ones
(for example, one car vs. two cars). Set to true to play the Single Sequence as defined in the
Sequence Strings tab. Set to false to select the Plural Sequence.
Prompt Strings This page allows the specification of zero or more Prompt Strings that can be
substituted dynamically into the phrase. Typically, the entries on this page are string literals
or the names of string variables. A Prompt String consists of one or more prompt identifiers
separated by white space. A prompt identifier can be scoped or unscoped by a handler name.
A scoped prompt identifier consists of the handler name, a colon, and the prompt ID (e.g.,
<HandlerName:PromptName>). All identifiers are case insensitive.
Variables A list of string type variables that are in the current handler. To assign a string to a
parameter, it must first be defined in the handler.
Parameters The substitution strings that are passed in at run-time to the sequence string.
The parameters are referenced as %1, %2, and so on in the sequence string, according to their
position in this list.
Prompt This read-only text box displays a prompt that has been selected using Pick Prompt,
but has not been assigned to a Parameter number.
Pick Prompt Opens the Prompt Editor for the selection of a prompt. After the prompt has
been selected, it will appear in the Prompt read-only text box. Pressing the >> button will add
the prompt to the Parameters list.

5-48Customizing the System 2017, Interactive Intelligence, Inc.


In this example, the value of the sCharacterPhrase variable will be substituted for <%1> in the
sequence string. This will play the number of letters that a caller must enter of their partys first or
last name. This string variable gets its value from selections made in the Dial by Name operation in
Interaction Attendant.
Sequence Strings A sequence string is the combination of prompts and variables that make up the
complete prompt to be played. This page is where the prompt is assembled. When a language is added
in Interaction Administrator, a tab will be added on this page for managing prompts in that language.
Handlers Any currently open handlers will appear in this list. Selecting a handler from the list
populates the prompt list with prompts that are stored with that handler. You must have the
prompt library handler open that contains the prompt that you want to use in the current handler.
Use Check the box beside the prompt sequence that you want to use.
ID The sequence string identifier for this prompt phrase.
Single Sequence The sequence to play if the Singular is true value is set to true.
Plural Sequence The sequence to play if the Singular is true value is set to false.
Delete The Delete button allows you to delete a sequence string. The sequence string is
deleted from the selected prompt library handler. Save and publish both handlers.
Edit The Edit button allows you to edit a sequence string. The sequence string is changed in
the selected prompt library handler. Save and publish both handlers.
Insert The Insert button allows you to insert a new sequence string. The sequence string is
inserted into the selected prompt library handler. Save and publish both handlers.

If you delete, edit, or insert a sequence string for a handler other than the current handler, save and
FOR YOUR
INFORMATION
publish that handler, too. When you attempt to publish the current handler, you will receive the
following window as a reminder:

5-49Customizing the System 2017, Interactive Intelligence, Inc.


Selected Sequence A read-only box that displays the scoped sequence string identifier of the
selected prompt phrase.
Sequence Notes A read-only box that displays any notes that were saved with the sequence
string when it was created.

In this example, DialByName04 is the Sequence String ID of the selected sequence. The same
sequence is entered into the Single Sequence and Plural Sequence fields because, in this case, there
is no plural to consider. The sequence for this example is:
<Prompt_Attendant:DialByName_PLEASE_ENTER_FIRST><%1><Prompt_Atten
dant:DialByName_CHARS_NAME_LAST>
This will result in the following prompt:
The prompt named DialByName_PLEASE_ENTER_FIRST from the Prompt_Attendant handler:
Please enter the first
The value of sCharacterPhrase which is the substitution string for %1:
3
The prompt named DialByName_CHARS_NAME_LAST from the Prompt_Attendant handler:
characters of your partys last name.

5-50Customizing the System 2017, Interactive Intelligence, Inc.


String Output On this page, you specify the name of a string variable in which to store the selected
sequence string. This variable can be used later in the handler in a Play Prompt Phrase step.

The Assemble Text Phrase tool is very much like the Assemble Prompt Phrase tool. It is used to build
FOR YOUR
INFORMATION
string sequences that will either be written to a log, email, or text media; or read using TTS. The Play
Prompt Phrase tool is used to have TTS read a Text Phrase.

PROMPT TOOLS PLAY PROMPT PHRASE

To play prompts or to have TTS read text strings in handlers, use the Play Prompt Phrase tool. This
tool allows you to define a sequence of strings that define the structure of a prompt that you want
to play and then substitute values at run-time to play the actual prompt. This eliminates the need to
use multiple Play Prompt tools in order to play a sequence of prompts.
The Play Prompt Phrase tool has many of the same properties as the Assemble Prompt Phrase tool.
Input The Input tab, for Play Prompt Phrase, is similar to the Input tab for the Assemble Prompt
Phrase tool. However, there is an additional property that identifies the call to which the prompt will
be played.
Call Identifier The unique identifier for the interaction. This defaults to Interaction1.

5-51Customizing the System 2017, Interactive Intelligence, Inc.


Prompt Strings This page allows the specification of zero or more Prompt Strings that can be
substituted dynamically into the phrase. Typically, the entries on this page are the names of string
variables or prompts. A Prompt String consists of one or more prompt identifiers separated by white
space. A prompt identifier can be scoped or unscoped by a handler name. A scoped prompt identifier
consists of the handler name, a colon, and the prompt ID (e.g., <HandlerName:PromptName>). All
identifiers are case insensitive.
The properties on the Prompt Strings page are the same as the properties on the Prompt Strings
page of the Assemble Prompt Phrase tool.

In this example, the value of the sMenuPhrase variable will be substituted for <%1> in the sequence
string. This will play a phrase that has been put together in a previous Assemble Prompt Phrase step.

5-52Customizing the System 2017, Interactive Intelligence, Inc.


Sequence Strings A sequence string is the combination of prompts and variables that will make up the
complete prompt to be played. This page is where the prompt is assembled. When a language is added in
Interaction Administrator, a tab will be added on this page for managing prompts in that language.
The properties on the Sequence Strings page are the same as the properties on this page in the
Assemble Prompt Phrase tool.

In this example, DialByName10 is the Sequence String ID of the selected sequence. The same
sequence is entered into the Single Sequence and Plural Sequence fields because, in this case, there
is no plural to consider. The sequence for this example is:
<%1><Prompt_Attendant:DialByName_RETURN_PREVIOUS_MENU>
This will result in the following prompt:The value of sMenuPhrase which is the substitution string
for %1. This phrase is built by several Assemble Prompt Phrase steps throughout this particular
handler. The final value of sMenuPhrase will depend upon settings in the Dial By Name operator in
Interaction Attendant. In the default system, the value of sMenuPhrase will be:
Please enter the first three characters of your partys last name. Use 7 for Q and 9 for Z. For
an operator, press zero. To hear the company directory, press the pound key (#).
The prompt named DialByName_RETURN_PREVIOUS_MENU from the Prompt_Attendant handler:
To return to the previous menu, press the star key.

LOCALIZING PROMPTS
Localizing IC for more languages is best achieved by applying a Localization Pack, if available, from
Interactive Intelligence.

5-53Customizing the System 2017, Interactive Intelligence, Inc.


Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following labs in your lab manual:
Lab 23: Create a Prompt
Lab 24: Using Tools Help
Lab 25: Working with Object Attributes
Lab 26: Using Custom Object Attributes
Lab 27: Using Custom DS Attributes
Lab 28: Looking Up Information in a Table

5-54Customizing the System 2017, Interactive Intelligence, Inc.


Chapter

Troubleshooting
Troubleshooting
6
www.inin.com/education 2017, Interactive Intelligence, Inc.
6.1 Troubleshooting

THE HANDLER DEVELOPMENT SERVER


It is essential to system stability that all customized handlers and new handler functionality be
thoroughly tested on a development server BEFORE the handler is published and managed on a
production system. A malfunctioning handler can interrupt the core business function of a company
(to support staff this situation is known as a Code Red).
If a development server is not available, then all new or modified handlers must be tested after
hours. Be sure to have a back out plan in case of failure. Many Code Red problems that Interactive
Intelligence support deals with are caused by untested handlers.

TROUBLESHOOTING STEPS
There are times when a handler will not behave in the way that you expect it to behave, especially
if it is a new or modified handler. At these times, it is necessary to troubleshoot the handler. There
are many reasons why a handler does not perform as expected. For example, a variable value not
set properly, the logic of the handler is incorrect, or there is an infinite loop in the handler. (Because
infinite loops are so troublesome, we will address infinite loops in more detail in the next section.)
Debug The first step in troubleshooting a handler is to put the handler in debug mode and follow it
through its steps, viewing variable values as needed. Usually, running a handler in debug mode is all
that is required to pinpoint any logic errors in a handler.
IP Tracing Tools Occasionally, a handler will work as expected when debugged, but will fail when
running in normal mode. A more complex method of troubleshooting is to turn on IP tools tracing and
duplicate the problem. This procedure is discussed in the IP.ininlog section of this module.

INFINITE LOOPS
An infinite loop is caused when you attach an exit path from a step back to a previous step in a handler,
and nothing occurs in between that causes the flow to stop or a different exit path to be taken.

6-02Troubleshooting 2017, Interactive Intelligence, Inc.


Interaction Processor will terminate a handler that has executed 10,000 steps. IP will then log a
message similar to the following in the Application Event Log:

HANDLER CONFIGURATION

A handlers step limit, priority, and maximum number of concurrent handlers can be set in the Handlers
Configuration dialog of the Handlers container in Interaction Administrator.

6-03Troubleshooting 2017, Interactive Intelligence, Inc.


Modifying these settings can have unintended consequences. Use caution when making changes.
CAUTION
Contact Support before changing these values.
File Name Each time a handler is published, Interaction Designer appends a new date code at the
end of each handler class file. Do not change this name.
Maximum Number of Concurrent Handlers The default, 0, means that there is no limit on the
number of concurrent instances of this handler that can run. For handlers that use a large number of
resources to run this setting can be changed to limit the number of instances of that handler can run
at one time.
Maximum Number of Handlers Queued When the maximum number of concurrent handlers is
reached, this setting indicates how many handler requests can be queued until a slot becomes
available. Any requests over this setting will be discarded. A message in the event log will state the
maximum queue limit has been reached.
Handler Priority Handler Priority can be set to Low, Normal, or High.
Step Limit The default step limit, 0, has a value of 10,000 steps. If you click No Limit, a -1 appears in
the box.

IP MANAGER
The IP Manager dialog can be useful when trying to identify potential problems with handlers
running on the IC server. The Current Activity page shows specific information about handlers that
are currently running on the system.
The IP Manager dialog is available in the Interaction Processor or Handlers container. Right-click in
the data view or select IP Manager from the shortcut menu.

6-04Troubleshooting 2017, Interactive Intelligence, Inc.


Handler Name This is the name of the handlers currently running on the IC server. This list is
dynamic and is likely to change when you click the Refresh button.
Class Handlers can be categorized as: Notification, Timer, Subroutine, Web, and SystemInitialization
handlers.
Identifier This is the handler instance identifier.
History The History tab displays the number of handlers currently running along with the total
number of handlers that have run since the current session started.

SETTING IP TRACE LEVELS


Tracing is the logging of messages generated by subsystems that details actions performed by that
system. The degree of detail written to the logs by each subsystem is determined by tracing levels.
This information takes the form of log messages that are recorded in a file and can be used to track
system performance. With a few exceptions, most subsystems start with the default tracing levels
configured to Status level (which includes status messages, warnings, and errors) or lower. A trace
level of Status or lower will return some log information, but usually not enough for a support
engineer to determine the root cause of a problem. Usually tracing must be at Notes level or higher
for support engineers to troubleshoot an IC system accurately.

6-05Troubleshooting 2017, Interactive Intelligence, Inc.


You can change the tracing levels from within the IC System Manager. To open IC System Manager,
select Start->Program->Interactive Intelligence->IC System Manager on the IC server. The Trace
menu allows you to set the tracing level for each subsystem. Use Trace Configuration to set levels on
the subsystems in the process tree. Use All Trace Configuration to set levels on all the subsystems
started by the Interaction Center. If you want (or need) to change the location where tracing logs are
stored, this utility can set the new site.
To change the Tracing Level:
1. Select the subsystem that you want to change.
2. Select Trace|Trace Configuration. This opens the Trace Configuration window.
3. Right-click the subsystem topic on which you want to reset Tracing.
4. Select Set Topic Levels. This opens the Change Topic Levels window.

5. You can change the Topic Level in three different ways: with the radio buttons, the slide bar, or by
typing a number directly into the numeric edit box.
By increasing the trace level for the IP log (and especially the Tools topic), you will be able to use the
log file to see every step processed by the handler, the parameter values for the step, and so on.

6-06Troubleshooting 2017, Interactive Intelligence, Inc.


Rights to configure tracing are set by your Interaction Center administrator.
FOR YOUR
INFORMATION

THE IP LOG
The Log Viewer Utility must be used to read IC log files. The default location of the IC log files
including the IP log is: \13\IC\Logs.
The IP log is used mainly for troubleshooting handler problems. To trace a call through the IP log,
you must have the Call ID.
The best way to walk through an IP log to troubleshoot a handler is to have a copy of the handler
available along with the IP log.

USING THE LOG VIEWER UTILITIY


The Log Viewer Utility is included with Interaction Center, allowing developers and administrators
to view the logs created by IC subsystems. The Log Viewer Utility allows you to open up any binary
IC log file and view the messages written to that log. From the Log Viewer Utility, logs can be further
filtered by specific criteria or time stamp.

6-07Troubleshooting 2017, Interactive Intelligence, Inc.


To open a log for viewing:
1. From the File menu, select Open.
2. The Open dialog box appears.

3. Select the date folder that contains the logs you want to view.
4. From the list of files, select the log of the subsystem that you want to view, then click Open.
5. The appropriate log opens.
The Log Viewer Utility Menu The Log Viewer Utility menu allows you to control the Log Viewer
Utility console. A toolbar on the console allows you to perform many of the Log Viewer Utility
functions by clicking the appropriate icons.
6-08Troubleshooting 2017, Interactive Intelligence, Inc.
File The File menu allows you to open, reopen, or close log files. You can also export open logs
from the File menu in to ASCII format. This will allow the logs to be read in a standard text editor,
such as Microsoft Notepad or WordPad. By default, log files are stored in a binary format that
cannot be read without the Log Viewer utility.
View The View menu allows you to set how you view the open log(s) and message(s). You can
select a message in a log and then open that specific message by selecting the Show Message
Detail Window option. The message will open in a separate window.
Filter The Filter menu allows you to filter the open log to view specific message types or
threads. This will often only be necessary when troubleshooting a problem, as instructed by
Interactive Support. You can filter by topic, context, or thread ID, or set a filter based on a search
string which you enter. You can also remove all current filters to return to the default view.
Search The Search menu allows you to search for a specific message or to jump to a specific
time stamp in the log.
Log files for days before the current day are automatically zipped by the IC system. To view these
FOR YOUR
INFORMATION
logs, they must first be extracted from the zip file.
Large logs and complex filters can affect system performance. If a log file is large, it is recommended
CAUTION
that the log be snipped using Logsnipper before opening it in Log Viewer Utility.

6-09Troubleshooting 2017, Interactive Intelligence, Inc.


LOG RETRIEVAL ASSISTANT (LRA)
Log Retrieval Assistant (LRA) is a utility that support representatives use to retrieve trace logs and
other information from a customers IC server. LRA is compatible with earlier versions of IC. LRA is
installed with the server. LRA must be configured before it can be used.
Using LRA, trace levels can be set and Dr. Watson settings can be configured on a remote IC server.
Users can also snip segments of event logs, trace logs, and other types of information from data
sources (such as the registry) where IC subsystems have written data. LRA then routes the
information to a support representative via the Internet. LRA sends notification messages to inform
the requester and the customer about details of each transaction.
LRA retrieves various types of troubleshooting information from a customers IC server, including:
IC subsystem trace logs.
Dr. Watson logs.
Application and System Event logs.
Dump of IC registry trees, or a portion thereof, including the main IC tree or just the Directory
Service portion.
Dump of IC file information (for example file name, time stamp, file size, CRC32, file version,
hotfix version, file attributes, and so on).
IC version information.
Customers LRA configuration.

Customers can push data to a support site without waiting for a support representative to make a
request. Customers can also choose to use the push feature to retain control of what logs are made
available outside their organization.

TROUBLESHOOTING TIPS
Use a Log Event step after a Failure path Add log event steps after most failure paths in order to
log the error to the Event log. Errors logged this way are much easier to find than consulting trace
logs. Use the Error log type sparingly. Use the Warning type instead unless the error is serious.
Use built-in constants to identify the handler name in the text of every Log Event step. Also
use constants to identify the previous step number that triggered the log event. Include a brief
description of the possible problem. Some telephony tools will follow the failure path even when
no real failure occurred. The Extended Get Key, for instance, will take the failure path if the caller
hangs up or is disconnected while the Get Key is playing prompts or waiting for input.
Use Informational log events to troubleshoot or verify handler functionality Informational
Event log messages can be created in a handler using the Log Event tool. Use them to verify
important steps in a handler or track major changes or unique events in a handler. They can also be
used to troubleshoot handlers by identifying failure paths or other unwanted behaviors. Use this
method rather than debugging handlers or consulting trace logs. Create an Assignment step with
the handler name to find errors in the Event logs easily.
Set break point in debug to skip over sections You can turn any step into a breakpoint after a
handler is already in debug mode. Your handler must already be in debug mode to set a breakpoint:
Right-click on the step you want to set as a breakpoint.
Choose Set Breakpoint from the menu that appears. The step color changes to red. When the
debug handler runs, it will automatically stop at this step.
Debug using custom notification Trigger your subroutine handler for debugging using a Send
Custom Notification command. Create a separate handler that has the Custom Notification initiator
followed by your subroutine.

6-10Troubleshooting 2017, Interactive Intelligence, Inc.


Use a Net Send to troubleshoot handlers Insert an Execute Shell Command step with a Net Send
command to quickly be notified of a troubleshooting event in a handler. Another option is to use
email tools and send the event to you.
Learn how to read the IP Log Every handler developer should be familiar with how to read the
information in the IP log. Reading the IP log is often be the only way to troubleshoot handler
problems. Occasionally, a handler will work when debugged but fail when running in normal mode. An
IP log will tell you exactly what was happening when a handler ran.
Write specific troubleshooting messages to the IP log Use the Write Trace Message tool to
indicate specific events such as conditions and selections you want to track in a problem handler.
These steps are not shown in the trace log even at the highest Notes level of tracing.

ADVANCED HANDLERS BEST PRACTICES


Store attributes in variables after retrieving them do not overuse Get DS Attr or Get DS Attrs
tools to retrieve the same attribute. Retrieve the attribute once then store it in a variable or an XML
context node.
Use the XML Create Node tool to create data structures for passing information into subroutines
Often, as you build a set of handlers, you collect more context information that various subroutines
need. Adding individual parameters to subroutines is the common method to pass that information,
but this process can get unwieldy you can find yourself adding a parameter to many subroutines,
just so that one supporting subroutine can receive that parameter when called. A better solution is
often a data structure a user-defined type to which you add elements/ fields. All of your subroutines
could take this structure as a single parameter. If you later add a field to the structure, you do not have
to change every subroutine, only the subroutines that actually use that field of the structure.
ID does not support user-defined data types (like data structures). But you can use an XML node
for the same thing. Use the XML Create Node tool to create one, then use XML Set/Get Attribute
to work with fields in the node. The downside to this approach is that the datatype for XML
attributes must be string. If you are handling integers and numerics as context data, then you would
have to convert to/from strings to store them in a context XML node. In the end, you will have to use
your best judgment to determine the best way to implement context data for this situation.
Store information subject to change outside handlers Design handlers to avoid making customers
open the handler and make small changes. Use server parameters, IA tables, or database tables to
store the information that may need to be changed like directory paths, file names, server names,
external numbers for blind transfers, and so on.
String manipulation tips:
Do not repeat string functions (StrLower, and so on) on the same variable unless its value
changes. Use temporary variables to store manipulated string values, if necessary.
Do not over-use string comparisons. Use integer or numeric comparisons where possible. String
comparisons compare each character individually. So comparing five = five would take four
times as long as comparing 5 = 5. (Note, however, that the first character that does not match
stops the comparison, so five = three would only compare the first character.) In addition,
string comparison is often accompanied by a StrLower to avoid case- sensitivity, thus increasing
the execution time even more.
Do not use packed strings to carry structured data between subroutines. Packed strings are
strings that contain multiple data elements, usually separated by some special character (for
example, Susan | Stone | 2880 Chicabuck Parkway | Punxsutawney | PA), usually manipulated
with the Parse String and List to String tools. Packed strings are problematic for maintainability
and for performance. Instead use independent variables for each structured element or use XML
nodes for structured data.

6-11Troubleshooting 2017, Interactive Intelligence, Inc.


Within a loop, only execute operations that change with each iteration of the loop do not include
static steps inside a loop.
Efficiency:
Minimize lookup steps by writing values to call attributes Avoid repeatedly looking up Directory
Services/Registry information by assigning the information to call attributes. Just retrieve the
attribute at any time in any other handler when you need the information again for the call.
Overall Project Tips:
Use server parameters for information specific to site Use server parameters to customize
handlers for certain projects or provide specific names to handler items.
Database:
Use stored procedures especially for date/time conditions Stored SQL procedures enhance the
performance of most queries depending on the complexity of the execution plan.
Always release and close connections before exiting a handler All of our handlers have cleanup
code that is called when the handler exits. However, to be extra safe (and to promote good
programming habits) explicitly release/close the connections in the handlers.
Prompts :
Prompt scripts Have a complete script available before recording prompts. If the script is for a
customer (other than yourself), verify with them that the scripts are correct.
Record Prompts using a phone with a high-quality headset When it is not possible to use a
professional recording studio, create prompt recordings over the phone using a high-quality noise-
canceling headset. Record the prompts in Interaction Attendant, or as voice mail to yourself and save
the voice mail attachments. The resulting .wav file will be in the right format.
ACD Queues :
Transfer ACD calls to a separate queue for voice mail, external transfers, or other special
processing ACD calls that need to go to voice mail or be transferred to an external number or
any other type of special additional IVR processing should be transferred to special dummy queues.
This will clean up the statistics for the parent queue and make reporting easier. For example, calls
that timeout while on hold in an ACD queue that then should be transferred to a cell phone should
first be transferred to a special handling queue. In this case, create a queue called XFER and transfer
the call there first. Then, do a Blind Transfer or other similar step to transfer the call to an external
number. This will keep the time spent on those calls from affecting the statistics of the parent
queue.

Review Questions
Complete the review questions for this module in your study guide.

Labs
Complete the following labs in your lab manual:
Lab 29: View the IP Log
Lab 30: Using Custom Notification
Lab 31: Skills Evaluation
Lab 32: Using Constants (Optional)

6-12Troubleshooting 2017, Interactive Intelligence, Inc.


Appendix

Handler Tools
A
www.inin.com/education 2017, Interactive Intelligence, Inc.
A.1 Handler Tools

ACD TOOLS

The ACD tools are used to implement Automatic Communication Distribution (ACD) in IC. These
tools were discussed in a previous chapter.

ACCUMULATOR TOOLS

Accumulators are generic, on-the-fly global variables. The accumulator tools on the tool palette
allow the user to create and modify the way accumulators behave and the types of information they
accumulate. Accumulators provide a place to store an attribute. For example, accumulators provide
a way for someone to gather (accumulate) a total number of calls. Accumulators are defined in the
Interaction Administrator, and Interaction Designer users can decide when they want to gather the
information that is stored in the accumulators.
While accumulators are defined in Interaction Administrator, the accumulator tools create
instances of accumulators and modify the value of those instances.

A-02Appendix A 2017, Interactive Intelligence, Inc.


Actions the Accumulator Tool can perform Accumulators are not values themselves. They are
definitions of types of data to be collected. An instance of an accumulator is an actual value being
saved with the system. The value of the instance can be set, retrieved, incremented, or locked. These
actions are described in the following list:
Set They set the value of an Instance (one for each data type: Boolean, DateTime, Integer,
Number, String).
Increment They increment (plus or minus) the value of an Instance (Integer or Number type only).
Get They get a value from the accumulator and bring it to the handler (one for each data type:
Boolean, DateTime, Integer, Double, String).
Lock/Unlock Allow/deny access to the value of an Instance (one for each data type: Boolean,
DateTime, Integer, Number, String). Locking is an advanced feature that might be needed if a
new value for an accumulator must be calculated using multiple steps. There is a chance that
a Lost Update could occur if another handler were allowed to change the accumulator value
while these multiple steps were executing.

BASIC TOOLS

The Basic tools are versatile tools that provide common programming functionality to the handlers.
They are used to create variables, assign values to variables, and evaluate the values of variables.
The Write Trace Message tool is used to write a message to the IP.ininlog file.
Table Lookup Tool The Table Lookup tool retrieves data from a table created in the Tables
container of Interaction Administrator (a subcontainer of the Interaction Processor container under
System Configuration).
This tool allows you to query specific columns within the table for specific values, and then return
corresponding values from the same row. Returned values must be bound to a variable to be used
within the handler.

A-03Appendix A 2017, Interactive Intelligence, Inc.


Table Lookup Process
1. Create a table in Interaction Administrator.
2. Add data to rows and columns in the table.
3. Create an index.
4. Save the table.
5. Add the Table Lookup tool in a handler.
6. Define values to lookup and return from the table.
Indexing Any columns that lookups will be performed against must be indexed. When you create
the table in Interaction Administrator, you can determine which columns are indexed and the type of
index to apply. Interaction Center Tables support two types of indexing: unique and multiple.
Unique Each entry in the column is unique (for example, account number) among all the
entries in that column. Table Editor warns you if it finds duplicates. Lookups on unique index
columns are faster than on columns with duplicate values. The variable to which you bind the
returned row value must be of string data type. Only zero or one row will be returned from a
lookup on a unique column.
Multiple Each entry in the column can have one or more occurrences of that value in the
column (for example, account type, date, and so on). Lookups on multiple value indexes are
slower than on columns with unique indexes. Since zero, one, or more rows will be returned from
a lookup on a multiple column, the type of variable to which you bind the returned values must
be a list of strings.

A-04Appendix A 2017, Interactive Intelligence, Inc.


BUFFER TOOLS

The Buffer tools manipulate binary buffers in a stack manner.


Data is put or get in a Buffer and kept as binary data within the buffer.
They are usually used in conjunction with the WebSphere MQ tools to exchange binary data.

CALENDAR TOOLS

The Calendar Tools can be used in a handler to place, retrieve, or edit data on a calendar server.
Presently, IC only supports the iPlanet, Microsoft Exchange, and Outlook calendar servers. This
release only supports Events, and only the Start Time, End Time, Location, Description, and
Summary Properties. Other calendars and features will be added in future releases.
The IC calendaring system is set up automatically when IC is installed to coincide with the mail
server that is selected during setup.

A-05Appendix A 2017, Interactive Intelligence, Inc.


DATABASE TOOLS

The Database tools allow handlers and subroutines to read from and update databases. Database
tools have many uses because they allow you to read from and write to a database outside the IC
server. While their uses are virtually unlimited, some uses are looking up passwords and retrieving
information to display in webpages.

DIRECTOR TOOLS

In Interaction Designer, tools for developing handlers with Interaction Director functionality appear
on a design palette tab named Director. Unless Interaction Director is installed, the palette will be
empty except for the Play Audio File (No Conference) tool, and that tool should not be used on a
non-Director system.

A-06Appendix A 2017, Interactive Intelligence, Inc.


EMAIL TOOLS

The Email tools are for sending, transferring, disconnecting, and otherwise manipulating emails and
email objects in Microsoft Exchange, Lotus Notes/Domino, or other supported email server.
Many of these tools can be used with email Server Parameters. For more information on email
Server Parameters, see Server Parameters in the Interaction Administrator Help.
The email Server Parameters that can be created are:
Save Sent Mail
Monitored Mailbox
Mail CPR Interval
Mail Temp Directory
Mail Archive Directory

The email tools cannot access folders located on users local machines. In order for the Open Folder
FOR YOUR
INFORMATION
tool to work, the folder being accessed must reside on the mail server. In other words, if you plan to
allow users to access their voice mail messages remotely (over the telephone), then users must have
their email delivered to their mailbox on the Exchange or Domino server.

FAX TOOLS

A-07Appendix A 2017, Interactive Intelligence, Inc.


The Fax tools are for building handlers that send and receive faxes automatically. (The Interaction
Fax viewer is for sending faxes manually.) The documents you fax can be in either Interaction Fax
format (.I3F files) or one of the Supported Bitmap File Formats.
For example, if you have a collection of documents that have been converted into a collection of
Interaction Fax format documents, you can build a handler that creates faxes containing a specific
collection of those documents.
The following steps describe of how the fax tools can be used as the basis for building fax-back
functionality via handlers.
1. Create the Fax Page List

A fax page list defines what will be faxed. The first step in any handler that sends a fax is the Create
Fax Page list tool. This tool specifies the Interaction Fax file or bitmap, and the pages within that file
to send.
2. Append Pages to the Fax Page List (optional)

You may need to use one or more Append Pages steps to add more pages to the fax. Append Pages
lets you create a fax from more than one file. This is useful if you want users to be able to request
multiple documents in a single phone call.
3. Create the Fax Object

Once you have compiled the fax page list, use a Create Fax tool to convert the list to a fax object that
can be processed by Fax Services.

A-08Appendix A 2017, Interactive Intelligence, Inc.


4. Create an Envelope, Print the Fax, or Email the Fax

Once you have a fax object, you can create a fax envelope, print the fax, or email the fax. Creating a
fax envelope is just specifying information about how the fax should be sent, such as the recipient
phone number, information that goes on the cover page, the time to send the fax, and an email
address to notify if the fax is sent or if the fax send fails. Fax envelopes are created using the Create
Envelope tool. You can also print the fax to a local or network printer using the Print Fax tool.
Finally, if you want to send the fax as an attachment to an email message, you can use the Send Fax
tool which is found under the Email Tools. You do not need to create an envelope if you are printing
or emailing the fax object.
5. Queue the Fax for Sending

If you want to send the fax via Fax Services, and you have created the fax envelope described in
step 4, you can queue the fax for sending with the Queue Fax For Send tool. This tells Fax Services
to send the fax using the information specified in the fax envelope. Once a fax has been sent, Fax
Services generates an Export Fax File event. This event starts the Fax Send Completed initiator.

FILE I/O TOOLS

Some File I/O tools create, read, and write to text files. For example, some non- Interaction
Center software can use or output text files. The text files created, read, or written to, can be

A-09Appendix A 2017, Interactive Intelligence, Inc.


shared by Interaction Center and the non-Interaction Center software. Other File I/O tools
provide TCP/IP functionality.
TCP/IP Tools The TCP/IP tools allow handlers to connect and communicate with other
applications on a LAN, WAN, or over the Internet. As long as the remote machine has a valid IP
address and the remote application is ready, the TCP/IP tools can send and receive strings and
integers.
The TCP/IP tools are typically used in the following order within a handler.
1. Open a Connection

Whether you are connecting to a remote computer or the remote computer is connecting to
Interaction Center, first establish a connection. When you establish the connection, the resulting
connection handle is used by the read and write tools to communicate with the remote computer.
If you are connecting to a remote computer, use the Tcp Connect tool. If the remote computer is
connecting to Interaction Center, use the Tcp Listen tool to monitor a port.
When the remote computer makes a connection, the Tcp Listen tool generates an event that starts
the Tcp Connection Accepted initiator. This initiator generates the connection handle.
2. Send and Receive Strings and Integers

Once the connection handle is established, the Tcp Read String and Tcp Read Integer tools can take
data sent by the remote computer and place it in a variable to use within the handler. Tcp Write
String and Tcp Write Integer can send data to the remote computer.
3. Closing the Connection

When the handler has finished sending and receiving data, we recommend that you close the
connection with the remote computer. The Tcp Close tool closes the connection stored in the
connection handle.

A-10Appendix A 2017, Interactive Intelligence, Inc.


GENERIC OBJECT TOOLS

The Generic Objects tools are for creating, transferring, disconnecting, and otherwise
manipulating objects.
Generic objects are used for routing additional interactions, such as a third-party chat, a video,
or a workflow document to agents in workgroups. These generic objects function like other
interactions within Interaction Desktop.
A generic object appears in the My Interactions tab in an agents workgroup queue in Interaction
Desktop, just like other interactions. When the agent clicks it, the application or document
pops open in Interaction Desktop. It can be transferred, disconnected, and so on just like other
interactions.

HOST INTERFACE TOOLS

Interaction Center has several tools that allow Interaction Center to communicate with
mainframes via the TN 3270(E) and TN 5250 protocols. The Host Server, an Interaction Center
Server subsystem, can log on to and perform operations through a terminal emulation. A handler
containing the Host tools can tell the Host Server to start a Telnet session with a mainframe (or
AS400) and pass information via screen scrapes. This is similar to performing a database put or get,
but the operation is performed through a mainframe terminal emulation running on the Host server.
Screen scraping is the process by which information is read from or to the fields in a terminal emulation.
This process does not introduce any security risks because the Host Server logs on just like any other
A-11Appendix A 2017, Interactive Intelligence, Inc.
terminal emulation user, allowing mainframe administrators to use existing security precautions.
Before you begin using Host tools and Host Server, purchase a license from your reseller or
FOR YOUR
INFORMATION
Interactive Intelligence. With the license, you will receive a key. Once you have entered the key and
the number of simultaneous connections granted with the license, you can begin to use the host
tools. These settings are configured in Interaction Administrator System Configuration Container.
The Host tools will not work without a license key.

ICON TOOLS

ICon tools contain tools for building handlers that interact with Interaction Conference.

INTERNET TOOLS

Internet tools are for building handlers that interact with people over the Internet. These interactions
can be through a web browser or through Internet chat. Using these tools, Interaction Center can
generate custom webpages and pop-up chat applets for a person browsing your website, format
appropriate URLs, and connect an agent to a party that requested a callback from your website.

A-12Appendix A 2017, Interactive Intelligence, Inc.


IP NOTES

The IpNotes tool set allows the handler author to store and retrieve named entities consisting of an
arbitrary number of named attributes of any of the ID-defined types Integer, String, or Date/Time.
Each attribute is a list of values of a particular type. An IpNote is available to all handlers on a given
server and accessed by name. IpNotes can be removed from memory explicitly, or can be set to
terminate automatically after a time interval specified at creation.
While IpNotes were designed for use with multi-site, many handler authors use IpNotes as a
substitute for global variables. The advantage of IpNotes over global variables is that global
variables lock the handler in which they are being used and IpNotes do not.

LDAP TOOLS

LDAP (Lightweight Directory Access Protocol) is a protocol for accessing information in an


information tree. The information tree is called a Directory Information Tree (DIT) and it is made up
of parent and child directory entries. Each directory entry has a unique name, called a Distinguished
Name (DN). Each entry also has a collection of attributes, which are name/value pairs that contain
information about the entry.
The LDAP tools allow Interaction Center to communicate with an LDAP server (LDAP v3 compliant)
to retrieve attribute values from the directory entries. We foresee this as an alternative to
retrieving user data from Interaction Center Directory Services. For example, a DIT might contain
information about 10,000 users, including first name, last name, and email address. Instead of

A-13Appendix A 2017, Interactive Intelligence, Inc.


setting up Interaction Center user accounts for each user, you can use the LDAP tools to look up the
user email addresses from the LDAP server.
Many of the LDAP tools require that you specify the DN that you want to query or write to. Discuss
the DIT structure of your company with your LDAP administrator so that your handlers can
construct valid DNs.
All entries contain attributes. Attributes are name/value pairs, and some attributes have more than
one value.
A person entry, might contain a uid (user ID), common name (cn), mail, and many more attributes.
The LDAP tools enable a handler to retrieve the value of an attribute in the directory entry you
specify. Therefore, you could use the LDAP tools to search for all entries where the last name is Doe
and return all email address attributes for those matching entries. Again, you will need to discuss the
entry types and their associated attributes with your LDAP administrator. The LDAP administrator
can give you a list of all entry types and their attribute names. You will need this information when
processing attributes within handlers.
The LDAP tools allow you to create entries, delete entries, read attribute values, write attribute
values, and delete attribute values.
Using the Tools
This section describes the tools in the order they should be used within a handler. For more
information, see the Interaction Designer Help on using each tool and for help in configuring each
tools parameters.

Login The Login tool logs a user into an LDAP server. The Login step must execute once in the
handler before other LDAP tools are executed. You must specify a Login ID and Password. The other
LDAP tools will have permissions based on that users permissions. For example, if the tool logs in as
administrator, the handler might have read/write access to the entire DIT. An individual user login
might grant access to only that users entry.

A-14Appendix A 2017, Interactive Intelligence, Inc.


Session Session uses the Login ID to generate a session with the LDAP server. Several other LDAP
tools that add, modify, and delete entries use the Session ID this tool generates. The session tool
typically follows the Login tool.
Read Entry Read Entry retrieves specified attributes from a specified DS entry. It then creates
an entry handle to that entry that you can pass to the Get Entry Attribute tool to extract the
attribute value(s).
Search Entries Searches a specified portion of a DIT for entries that match one or more search
criteria. The search criterion consists of attribute/value pairs and allows several types of wildcard
matching. You also specify the attribute/value pairs you want to return for all matching entries. The
matches are placed in a search result object.
Next Entry The Search Entries tool generates the search result object that can contain multiple
matching entries. There is an iterator in the search result object that points to one of those entries.
The Next Entry tool generates a handle to the entry that the iterator is pointing to, and then moves
the iterator to the next entry in the search result object. The entry handle can then be passed to
the Get Entry Attribute tool (just like the entry handle the Read Entry tool creates. When all of the
entries have been read, this tool takes the End of List exit path.
Get Entry Attribute Get Entry Attribute takes an entry handle (generated by the Read Entry or
Next Entry tool) and extracts the value of an attribute you specify. The value must be one of the
values you requested with the Read Entry or Search Entry tools. The attribute values are placed in a
list of string variables. This is because an attribute can have more than one value.
Add Entry Creates an entry at the location you specify. You can also specify the entrys attributes
and their values.
Modify Entry Changes the value of one or more LDAP entry attributes. You can only specify one
value for each attribute. However, if an attribute already has a value, you can use this tool to specify
one additional value.
Add Operation Creates an LDAP operation and adds it to the operation list for execution with the
Add Entry Ex or Modify Entry Ex tools. Operation lists are useful in LDAP because they allow you
to perform multiple operations on multiple attributes over one connection to the LDAP server. For
example, a caller might choose to modify their password and change several other personal settings
through an IVR. The handler could add all of these operations to a list and then execute them.
Specify an integer for the type of operation to perform.
To create a list of multiple operations, you will probably use many instances of this tool in a handler
FOR YOUR
INFORMATION
or create a loop so that this tool executes several times.
Modify Entry Ex While the Modify Entry tool allows you to modify a single attribute, the Modify
Entry Ex tool allows you to modify multiple attributes and to assign multiple values to a single
attribute. This is useful because it reduces the network resources required to execute multiple
operations. The operations list that this tool executes includes add, delete, and modify entry
operations. Use the Add operation tool to create an operation and add it to an operation list. You
might use Modify Entry Ex in a handler when a caller selects several configuration options in a single
IVR session. Each configuration option could be stored in the handlers operation list and executed
simultaneously before the handler ends.
Add Entry Ex Add Entry Ex creates an entry like the Add Entry tool, but allows you to use an
operation list to assign multiple values to an attribute.
Delete Entry Deletes the specified LDAP entry (and all of its attributes). Move Entry Changes
the RDN attribute and changes the parent. All of the attribute values remain unchanged except for
the UID attribute.
Rename Entry Changes the RDN attribute of an LDAP entry without changing its parent. All of the
attribute values remain unchanged except for the UID attribute.

A-15Appendix A 2017, Interactive Intelligence, Inc.


LIST TOOLS

List tools access and sometimes modify the contents of a list variable. List variables are like regular
variables, except that they can hold more than one value. For example, a variable of type ListofString
can contain two or more string values. List variables are created using the InsertAtHead and
InsertAtTail tools.
List variables allow you to hold multiple values of a specific type. For example, a List variable of a
string type could contain many string values. A list variable can be declared for each of the following
data types: String, Integer, Boolean, Database, DateTime, DBConnection, and Numeric. There is no
limit to the number of elements in a list.
Each element in a list variable is assigned a place number. The first place number is always zero, the
second is one, the third is two, and so on. The first element in a list is called a Head. Therefore, the
Head of a list is always at place number 0. The end of a list is called a Tail. The place number for a tail
is always the number of the last element in a list. Therefore, the place number of the tail can change
as elements are added or removed from a list.
You might want to use a list variable to store multiple items retrieved from multiple fetches to
a database. For example, if you have a handler that allows callers to retrieve information on all
financial transactions that have occurred for a specific account over the past five days, you could
have a step that fetches information on all transactions and stores them in a list variable.
List variables can be created for the following data types:
Accumulator Lock Key
Boolean
Call Id
Conference Id
Database
Date Time
DB Connection
Diagnostic Data
Fax Envelope Ids
Fax File Ids
Fax Object Ids
Fax Page List Ids
File Handle
Host Interface Connections
A-16Appendix A 2017, Interactive Intelligence, Inc.
Integer
Mail Folder
MQConnection
MQObject
Numeric
Prompt
Recording
Queue Period Statistics
Recording Id
Socket Handle
String
Web Connection

MONITORING TOOLS

Monitoring tools enable a handler to obtain information about a subsystem such as its CPU usage,
memory usage, thread count, or how long it has been running and use that information to build
an event log message. There are also Monitoring tools allowing a handler to restart or stop an IC
subsystem.
Monitoring tools were developed for internal testing purposes. Most customer sites would not
need to use these tools since Remoco provides most of this functionality.

A-17Appendix A 2017, Interactive Intelligence, Inc.


MULTI-SITE TOOLS

Multi-Site tools are similar to IpNotes tools and UMF tools. They provide functionality for
developing handlers that work with multi-site.

OCR TOOLS

The OCR tools are an extra set of tools that ship with the IC OCR. These tools provide some of the OCR
functionality in IC, although you must also install OCR and Export Server before OCR will work correctly.

A-18Appendix A 2017, Interactive Intelligence, Inc.


PERSONAL RULES TOOLS

Personal Rules are settings inside your Interaction Desktop which allow you to automatically
manage interactions. For example, Rules enable you to route certain specified interactions directly
to voice mail at certain times of the day. There are many other possible Rules that a user can create
in Interaction Desktop.
With these handler tools, you can extend the Rule functionality to other events generated by IC.
The Rules create a list of actions. You can then look up any action on the list and get its parameters.

PROCESS AUTOMATION TOOLS

The Process Automation tools enable handlers to interact with the Interaction Process
Automation application.

A-19Appendix A 2017, Interactive Intelligence, Inc.


RECO TOOLS

The Reco tools support the use of speech recognition in handlers. Many of these tools provide
similar functionality as telephony tools. For example, the Reco Basic Input is similar to Extended Get
Key, except that it will recognize voice input and DTMF input.

REPORTS TOOLS

Every 30 minutes (or at some other interval you specify in Interaction Administrator), Queue
Manager generates statistical information about the activity of each queue. This information
includes the number of items that were in the queue and other statistical information about those
items. For reporting purposes, the statistical information can be generated in several ways:
First, Queue Manager always generates statistical information for specified queues for every item.
Second, you can designate certain items as belonging to Stats Groups. Stats groups can contain
items that can be dispersed among different queues. At the designated interval when other
statistics are generated, Queue Manager will generate statistics for Stats Groups, even if those
items reside on different queues. Stats Groups are a way for you to monitor a group of calls or
other items despite their location within the system.
Third, you can designate certain items as belonging to a Report Group. Report Groups are useful
for reporting on a subset of the calls within the queue or Stats Group. When Queue Manager
generates statistics for a queue, it additionally generates statistics for all the items belonging to
a Report Group. An item can belong to only one Report Group.

A-20Appendix A 2017, Interactive Intelligence, Inc.


SMS TOOLS

Short Message Services (SMS) tools allow users to exchange text messages over cell phones.
To make use of SMS Support, you will need to connect with an SMS Broker. An SMS Broker is a
company that takes care of routing the SMS Messages to cell phones and collects SMS Messages
from cell phones.

SOAP TOOLS

SOAP (Simple Object Access Protocol) is a lightweight XML-based messaging protocol used to
encode the information in Web service request and response messages before sending them
over a network. SOAP messages are independent of any operating system or protocol and can be
transported using various Internet protocols, including SMTP, MIME, and HTTP.
SOAP tools provide a means for a handler to call a web server, request information, and have the
information returned to the handler.
You might create a handler that has a Timer Initiator that accesses a web server that provides stock
EXAMPLE
quotes. Every 20 minutes, while the market is open, the handler would request stock quotes and
write them to a file.
There are many publicly available web services. www.xmethods.net lists many of these free
FOR YOUR
INFORMATION
web services.

A-21Appendix A 2017, Interactive Intelligence, Inc.


SCHEDULE TOOLS

These tools are used by Interaction Attendant to retrieve schedules that were created in Interaction
Administrator or Interaction Attendant. While it is possible these tools be used in other handlers,
the handler author should have a solid understanding of IC IVR handlers, call flow, retrieving
Directory Services (DS) attributes, and branching based on the values of DS attributes. These tools
are currently used out-of-the-box in the Interaction Attendant handlers. They can be used outside
Interaction Attendant in a future release.

STATALERTSERVER TOOLS

A-22Appendix A 2017, Interactive Intelligence, Inc.


SYSTEM TOOLS

The System tools perform various functions. Among other things, the System tools allow you to
create handlers that look up, create entries, and update entries in the Interaction Center Directory
Services. Some of these tools allow you to gather diagnostic information, pause the handler, perform
certain call transfers, and so on.

TUI TOOLS

TUI Tools contains various tools including:


Find Localized File returns the path to a localized version of a .wav file.
Find User By TN takes a phone number and searches for a user who has this phone number set
as an attribute value in their user properties information (for example Home Phone, Business
Phone, Mobile Phone, and so on).
Create Private Contact Grammar creates an ABNF grammar file containing the private contacts
grammar according to the specified parameters.
Create Calendar Session creates a calendar session usable with the Calendar Tools.

Note that Attendant Email Logical Transfer, TUI Get Catch, TUI Menu Attributes, and TUI Session
are for internal Interactive Intelligence use only.

A-23Appendix A 2017, Interactive Intelligence, Inc.


TELEPHONY TOOLS

The Telephony tools perform various call-related functions within Interaction Center, such as client
functionality like Pickup, Mute, Disconnect, Conference, and so on; getting and setting interaction
attributes, playing prompts and strings, recording calls, querying queues, and much more.
When using the Extended Get Key tool step to gather digits, it will log all of the captured digits in
CAUTION
plain text to the TsServer and IP subsystem trace logs. If you are gathering sensitive information,
such as credit card numbers, account Personal Identification Numbers (PINs), or Social Security
Numbers (SSNs), set Suppress logging of the input digits to true on the third Inputs tab of the
Extended Get Key tool step:

A-24Appendix A 2017, Interactive Intelligence, Inc.


UMF TOOLS

The Universal Messaging Facility provides a number of tools that a handler author can use to
construct arbitrarily complex messages and send them to other handlers published on the same
server. The sending of a message triggers one or more initiators. The initiators have inputs that
allow the author to specify which handlers will trigger based on data contained in each message.
The originating handler can create a message and add elements of various types. Then it can choose
to send the message as an event (asynchronously) to which it expects no reply or as a request
(synchronously). When a message is sent as a request, the tool step in the originating handler waits
for a message to be returned before continuing.
The receiving handler uses the tools that get data elements from the message. The receiving handler
can in turn use the message construction tools to create and send a message to yet another handler
or to send a response back to the original handler if appropriate.
This subsystem depends on some basic Interactive Intelligence components and on Microsofts
FOR YOUR
INFORMATION
MFC libraries. These items must be present in executable form at runtime, and represented by .lib
and .h files at compile time.

VOICEMAIL XML TOOLS

A-25Appendix A 2017, Interactive Intelligence, Inc.


VoiceXML is the W3Cs standard XML format for specifying interactive voice dialogues between a
human and a computer. It allows voice applications to be developed and deployed in an analogous
way to HTML for visual applications.
The VoiceXML Interpreter optional feature is integrated into the IC platform. The tools available
here are related to activating VoiceXML sessions. Handlers process incoming calls and decide if a
call should be routed through a VoiceXML application. The handler then invokes a tool step which
transfers the call to the VoiceXML Interpreter, and a VoiceXML session is activated. The VoiceXML
Interpreter attempts to load and parse the document, and if successful, it takes ownership of the call.

WEB INTERACTION TOOLS

Web Interaction Tools are for working with ACD Interactions that originate from a web interface.
Much of the functionality provided by these tools mirror functionality provided by similar Telephony
tools used for calls. For example, Alert Interaction is similar to Alert, except that it is used with web
interactions instead of phone calls.

WEBSPHERE MQ TOOLS

IBM WebSphere MQ messaging software enables business applications to exchange information


across different operating system platforms. The WebSphere MQ tools allow handlers to interact
with a WebSphere MQ Queue Manager. If you are not already using WebSphere MQ applications at
your company, then you will never need to use these tools.

A-26Appendix A 2017, Interactive Intelligence, Inc.


The documentation for the WebSphere MQ tools offers brief explanations, but refers you to your
WebSphere MQ documentation for details. This is because the WebSphere MQ tools are just a
handler interface to the WebSphere MQ API.
These tools will not work unless the WebSphere MQ server is running on the Interaction Center
server. This server can run as a service, and you should see your WebSphere MQ documentation for
more information on installing and running WebSphere MQ server as a service.
IBM maintains online versions of all WebSphere MQ documentation under the Library section
of their support page, http://www-306.ibm.com/software/integration/wmq/support/. For
more information, refer to the Quick Beginnings guide on WebSphere MQ and WebSphere MQ
server installation.

XML TOOLS

XML tools can be used to create, manipulate, and use XML documents in handlers. XML tools can
be used to simulate a data structure in handlers. An XML document can be passed as a parameter of
XMLNode data type, among subroutines.
You can create an XML document that contains all of the attributes that you want to associate with
EXAMPLE
an interaction. Then, rather than using many attribute lookups you can refer to the XML document.
You can configure which tool categories appear in the tools page of the design palette by modifying
FOR YOUR
INFORMATION
the I3\IC\Server\DesignerRegisteredTools.lst files. This ASCII file contains a list of the DLLs that
populate the tools page of the design palette. Placing a # in front of a DLL will comment out that
line, preventing that category of tools from appearing in the palette. When Interaction Designer is
started, it first looks in the directory from which it was started for the DesignerRegisteredTools.lst
file. If it does not find it there, it checks the system path. The first DesignerRegisteredTools.lst file
found is the one that will be used.

A-27Appendix A 2017, Interactive Intelligence, Inc.


Appendix

Handler Pre-Class Materials


B
Interaction Center Platform Overview
Interaction Center Architecture
Terminology
Introduction to Interaction Designer

www.inin.com/education 2017, Interactive Intelligence, Inc.


B.1 Interaction Center Platform Overview

THE INTERACTION CENTER PLATFORM


The Interaction Center (IC) platform is a sophisticated engine capable of automating virtually every
aspect of business communication. The Interaction Center platform acts as the central point of
control for all business communication.

The Interaction Center platform captures and processes every communication event, like: a user
lifting a telephone handset, a call coming in, a fax going out, an on-line customer clicking a button on
a web page, a new email, a call transferred from one extension to another, and so on.
Interaction Center is implemented as a distributed client-server application. The server portion, called
the Interaction Server, runs on a Windows 2008 Server. The Interaction Server serves as an interaction
processor, offering a digital PBX, ACD, IVR, email, voice mail, and fax processor, and dozens of other
coordinated roles that can be administered via a single interface, the Interaction Administrator.

B-02Appendix B 2017, Interactive Intelligence, Inc.


B.2 Interaction Center Architecture

INTERACTION CENTER SUBSYSTEMS


All the subsystems of the Interaction Center platform work together via a central communication
hub - Notifier. Each subsystem is critical to the overall system.

Interaction Center has a modular software design that logically separates each communication
element from the other communications components. By taking this approach, if one part of the
product becomes fractured for some reason, the others will still function. Also, when one part
of the product is in need of updating, just the parts associated with it are updated. Therefore, the
entire system does not need to be upgraded.

SUBSYSTEM OVERVIEW
Before discussing handlers and objects, it is important to understand the underlying components
of the Interaction Center platform. The IC platform is a distributed client-server application. Many
subsystems provide one or more coordinating services to the other IC server subsystems. Each IC
subsystem provides specific functionality on the IC server.
Notifier subsystem Acts as the switchboard-hub through which the other IC subsystems
communicate with each other.
Directory Services (DS) subsystem Stores user, workgroup, line, and other configuration
information. The Interaction Administrator usually puts the configuration information into DS.
Web Services subsystem Provides Internet and chat functionality.
Automated Communication Distribution (ACD) server subsystem Performs the calculations
necessary for intelligently routing interaction to available and appropriate agents.

B-03Appendix B 2017, Interactive Intelligence, Inc.


Administration Services subsystem Caches Directory Services information for rapid access by the
other subsystems.
ClientServices subsystem Keeps track of Interaction Desktop statuses.
Email Services subsystem This subsystem integrates IC with email systems such as Microsoft
Exchange, Lotus Notes, Novell GroupWise, Sun/iPlanet Messaging Server, and other SMTP/IMAP-
based systems.
Interaction Processor (IP) subsystem Runs handlers. The heart of the Interaction Center platform
is an event-handling engine called the Interaction Processor (IP). Every eventa new incoming call,
an outgoing fax, a web page hit, a busy number, and so onis tracked by IP. As it detects these new
events, IP is capable of invoking handlers. A handler is an application designed especially to process
a particular type of event. Handlers can perform a myriad of actions including playing voice prompts,
detecting the touchtone digits, sending faxes, transferring calls, consulting databases, generating web
pages, and much more.
Telephony Services (TS) subsystem Manages call objects.
Fax Services subsystem Performs most of the fax functionality including receiving and sending faxes.
Log Server subsystem Writes reporting data.
Queue Manager subsystem Performs four functions in IC. It creates and deactivates queues,
coordinates activity of items on queues, manages information about items in a queue, and maintains
statistical information on queues and queue items.

CUSTOMIZING THE SYSTEM

Interaction Center is a powerful communications platform. Despite extensive out-of- the-box


functionality, many institutions have customizations that they want to implement on their telephony
system. Interaction Designer and handlers provide the means for any desired customization
requirements to the IC system.

B-04Appendix B 2017, Interactive Intelligence, Inc.


HANDLERS IN IC
Handlers are programs built in Interaction Designer that perform some action or actions in response
to the occurrence of an event: every eventa new incoming call, an outgoing fax, a web page hit, a
busy number, and so on. Handlers can perform a myriad of actions including:
Playing voice prompts
Detecting the touchtone digits
Sending faxes
Transferring calls
Consulting databases
Generating web pages
And much more

Review Questions
Complete the review questions for this module in your study guide.

Labs
There are no labs associated with this module.

B-05Appendix B 2017, Interactive Intelligence, Inc.


B.3 Terminology

HANDLER TERMS
Creating and modifying handlers requires that you think logically about the task at hand to develop a
handler program to perform that task. In other words, you will be programming.
In this section we are going to discuss the terms that we will use when defining, creating, and
manipulating handlers. It is important that we discuss these terms even if you have been developing
programs for many years. Some terms differ from one programming platform to another.
In this section, we will define the terms as they apply to the Interactive Intelligence development
environmentInteraction Designer.

LOGIC
Logic is the sequence of instructions in a handler. It is a set of ordered steps for solving a problem. To
work properly, these steps require unambiguous rules that have a clear stopping point.

DATA TYPES
Input and output parameters expect a specific type of data. The value and data type of a variable
must match to ensure data integrity. A parameter that expects a value of an integer cannot accept
a string. A parameter that expects a value of string cannot accept a Boolean expression (true or
false). If you try to assign the wrong type of value to a parameter, you will receive an error message
indicating that the expression is incomplete.
Data types can be categorized in two groups:
Normal
Extended

NORMAL DATA TYPES


Normal data types can be used in expressions, can be written to and read from a database, and can
be displayed in an HTML form. For example, integer is a normal type. Integer values can be used in
expressions, can be read from and written to databases, and can be displayed in an HTML document.
Normal data types include:
String String values can be any sequence of text characters. When a variable expects a string value,
you can assign that variable a literal value (like Dog, Turk182, or 34.56), build an expression that
results in a string value, or type the name of a string variable that is assigned a value in some other step.
Integer Integer values can be any positive or negative non-decimal numbers including zero. They
include all numbers in the whole number set. When a variable expects an integer value, you can assign
that variable a literal value (like -1, 0 or 434), build an expression that results in an integer value, or
type the name of an Integer variable that is assigned a value in some other step.
Boolean Boolean values can have a value of either true or false. For example, the expression 4<5
results in a value of true. The expression 5<4 results in a value of false. When a variable expects a
Boolean value, you can assign that variable a literal value of true or false, build an expression that
results in a value of true or false, or type the name of a Boolean variable that is assigned a value in
some other step.

B-06Appendix B 2017, Interactive Intelligence, Inc.


Numeric Numeric values can be any positive or decimal numbers including zero. They include all
numbers in the Real number set. When a variable expects a Numeric value, you can assign that
variable a literal value (like -1.5, 0, or 45.9348), build an expression that results in a numeric value, or
type the name of a numeric variable that is assigned a value in some other step.
Date/Time DateTime values contain information about a specific date and a time. The information
contained in a DateTime value is the year, month, day, hour, minute, and second. The DateTime
operators process and produce DateTime values.
Lists of (any normal or extended type) Lists contain one or more values of any normal or extended
type. A List of strings variable can contain many string values. Each position in the list has a number.
The first position is always position zero.
A list cannot contain another list; in other words, you cannot have a list of lists.

EXTENDED DATA TYPES


Extended data types can be thought of as handles for values that are foreign to Interaction Designer.
Extended values cannot be used in expressions, cannot be read from or written to a database, and
cannot be displayed in an HTML document.
Extended values hold information that is useful for hardware and software outside the base
Interaction Center system. These external types are useful because they extend the functionality
of the Interaction Center system. New external types can even be added to the Interaction Center
system to allow Interaction Center to integrate with non-Interaction Center hardware and software.
Here are some of the extended data types you will encounter in handlers. You will probably
encounter others, and new types are created with each Interaction Center release:
Call Identifier variable An identifier for a call object created by the Telephony Services subsystem.
You can convert a Call ID to an integer value with the Call ID to Integer tool, and an integer value to
a Call ID with the Integer to Call ID tool.
Database Connection variable DBConnection values contain a handle (or identifier) for a database
connection. When a DB GetConnection step connects to a database, the result (or output) of that
step is a handle for the connection that is stored in a Database Connection variable. Several database
tools use a Database Connection value to read from and write to databases. Because DBConnection
values are extended data types, they cannot be modified in expressions.
Database variable Database variables contain a handle (or identifier) for a database. When a
DBOpen step opens a database, the result of that step is a handle for the opened database that
is stored in a Database variable. This Database value is later used by a DBGetConnection step to
establish a connection with the database. Because Database values are extended data types, they
cannot be modified in expressions.
Fax ID variable An identifier for a fax object (which contains a fax) created by the Create Fax tool.
File Handle variable An identifier for a file opened with the File Open Read or File Open Write tool.
Folder ID variable An identifier for an opened folder in an email application, such as Microsoft
Exchange or Lotus Notes/Domino.
Hconn variable An identifier for a connection with an MQSeries application created with the
MQConnect tool.
Host Connect variable An identifier for a mainframe or AS400 connection created by the Host
Connect tool.
Socket Handle variable An identifier for a TCP/IP connection created with the TCP Connect Tool.

B-07Appendix B 2017, Interactive Intelligence, Inc.


Web Connection variable WebConnection values contain a handle (or identifier) for a World Wide
Web connection. When a GenerateHTML step creates an HTML document, that document
is sent back to a person browsing the web via the value of the WebConnection variable. The
WebConnection value is also used by several chat tools. Because WebConnection values are
extended data types, they cannot be modified in expressions.

VARIABLES
A variable is a symbol or name that stands for a value. You can think of a variable as a container
that holds a value which can vary. For example, in the expression x+y, x and y are variables. The
value of x and y could be anything, such as 4 and 5, or 3.14 and 5.667.
Variables can represent numeric values, characters, or character strings. Variables play an important
role in computer programming because they enable programmers to write flexible programs. Rather
than entering data directly into a program, a programmer can use variables to represent the data.
Then, when the program is executed, the variables are replaced with real data. This makes it possible
for the same program to process different sets of data.
A variable is made up of three parts:
Name A label for the variable. You use the variable name to make reference to it.
Value A specific piece of data that matches the variables data type.
Data type This indicates what type of value a variable holds, such as an integer, a numeric, a
character, and so on The value of the variable must match this data type.
Literal Value A literal value is written exactly as it is meant to be interpreted. A literal value can be
a number, character, or a string.
x=7
EXAMPLE

(x is a variable, 7 is a literal)
In the above example, x can be evaluated as any number. It is a variable, but 7 can only be
evaluated as the number 7.

EXPRESSIONS
An expression is any legal combination of symbols that represents a value. Every expression consists
of at least one operand and can have one or more operators. Operands are values and operators are
symbols that represent actions.
x+5
EXAMPLE

(x and 5 are operands and + is an operator)

CONSTANTS
Constants are similar to variables in that they also store values. However, as the name implies, the
value of a constant will not change throughout the execution of an application. There are several
built-in constants in Interaction Designer that can be used in handlers.
$ComputerName Returns the name of the computer on which the handler is running.
$CurrentStepID Returns an integer that contains the step ID of the currently executing step.
$HandlerName Returns the name of the currently running handler.

B-08Appendix B 2017, Interactive Intelligence, Inc.


$HandlerStack Returns a string with the following format:
<HandlerName>:<StepID>|[<HandlerName>:<StepID>|]
The string specifies the current steps executing handler stack.
Step 5 in handler A calls handler B. The currently executing step in HandlerB is step 6.
EXAMPLE
$HandlerStack would return the following: B:6|A:5|
The order of the handlers listed in the string from left to right goes from the currently executing
handler and works its way up the stack.
$Now Returns the current date and time.
$PreviousStepID Returns an integer that contains the step ID for the step that led into the
currently executing step.

CONDITIONS
A condition refers to an action that takes place only if a specific condition is met. Conditional
expressions enable a handler to act differently each time it is executed, depending on the input.
Conditions evaluate a single expression to determine whether the outcome is true or false.
If the sun is up, it must be daytime, and I need to go to work.
EXAMPLE

Otherwise, it must still be night, and Ill go back to bed.


In this example, the condition being tested is whether the sun is up or not. If you were to write this
programmatically, you might write:
IF sun up,
THEN work
ELSE
sleep
Selection
A Selection function is similar to a condition function. However, a selection function is able to evaluate
multiple expressions to determine whether the outcome of any of these tests is true or false.
If the value is 1, then the caller wants access to voice mail.
EXAMPLE
If the value is 2, then the caller wants access to faxes.
If the value is 3, then the caller wants to change status.
If the value is 4, then the caller wants to talk to the boss.
If the value is something else, disconnect the call.
Notice in this example, the variable is the same, but the values are different, and the logical path that
is taken next depends upon that value.

LOOPING
A loop is a series of instructions that is repeated until a certain condition is met. Each pass through the
loop is called an iteration. You just experienced looping in the previous Selection example. We kept
checking the same variable but for different values. Looping is a necessary function in programming.
You have a list of employee records in a database and you want to verify that you have a home phone
EXAMPLE
number for everyone. The program logic needs to go through each record one at a time and see if
there is a phone number in the record.

B-09Appendix B 2017, Interactive Intelligence, Inc.


Your logic would look like this:
1. Retrieve a record from the database.
2. If the phone number is not blank, then go to #1.
3. If the phone number is blank, then write the employee name out to a file.
4. Go to #1.
Keep in mind, this is simple logic without any error checking to see if it is at the end of the database.
If you were to program this logic exactly like the example, you would have an infinite loop. An infinite
loop will cause the program to continue to run through this logic endlessly, which will likely cause a
server crash. Therefore, when you intentionally put a loop in your logic, it is imperative that there is an
exit route. Your programming must contain logic that determines at what point the loop should stop.

OBJECTS
In Interaction Center, an object is an entity on which actions can be performed. Any entities that IC
can manipulate are considered objects.
Calls
Faxes
Chat sessions
Email

When a call comes in to IC, a call object is created. That call object can have actions performed on
EXAMPLE
it, like being transferred or being placed on a users queue.

ATTRIBUTES
Objects can have attributes. Attributes define characteristics of objects. For example, attributes of
a person can be brown hair, blue eyes, and so on Attributes that describe a call object are things
like Call ID, ANI/DNIS information, and so on.

EVENTS
An event is an action or occurrence detected by a handler. As discussed previously, calls, faxes, chat
sessions, email, and other entities that IC can manipulate are considered objects. These objects have
associated events that tell IC how to treat the object. Some of the events are outbound call, call
transfer, call hold, conference a call. Objects are entities that IC can manipulate. Events are what
IC can do to those entities.
Events serve two purposes in IC:
An event can tell Interaction Processor to start an instance of a handler Each handler has been
designated to respond to a particular event. For example, when Telephony Services generates an
Incoming Call event, the Notifier tells Interaction Processor that the event has occurred. Interaction
Processor starts an instance of the handler configured to run when the Incoming Call event occurs.
An event can modify the information regarding the object This information is stored as an
attribute of the object. For example, an event generated by an incoming call creates (or collects)
information about that call, such as the Caller ID and the name of the line carrying the incoming call.
The information contained in the attributes can be used by the handler to make decisions about what
to do with the object.

B-10Appendix B 2017, Interactive Intelligence, Inc.


HANDLERS

A handler is an .ihd formatted file that is made up of individual steps that form logic. Handlers
respond to events and handles them in various ways, depending on the logic of the handler.
A handler is nothing more than a series of discrete steps or tasks that, when combined, produce
some results or manipulate an object in some way. When linked together, handlers are powerful
programs that determine the behavior of IC. Handlers allow you to customize IC according to your
companys needs.
Certain handlers, called base handlers, should NEVER be modified. Customization points are
CRITICAL
provided for modifications.
Interaction Attendant uses handlers to perform the inbound call routing operations that you design
in Attendant. The Attendant handlers should NEVER be modified.

SUBROUTINES
Subroutines are handlers started by other handlers, as opposed to handlers started by events on the
IC server. Subroutines are useful for many reasons:
A subroutine nicely encapsulates a set of logic into a single callable action You can reuse a
subroutine by calling it from any handler where that logic is appropriate.
Subroutines ease your maintenance burden By keeping your logic in simple, small modules, you ease
the overall maintenance time by working on smaller components and not on a large monolithic file.
Subroutines make handler building more visually manageable and understandable Handlers with
hundreds of steps can be hard to understand and manage. A few subroutines can make a large
handler easy to modify and understand.
Essentially, by using subroutines properly, you break the handler logic down into bite-sized pieces.

B-11Appendix B 2017, Interactive Intelligence, Inc.


Review Questions
Complete the review questions for this module in your study guide.

Labs
There are no labs associated with this module.

B-12Appendix B 2017, Interactive Intelligence, Inc.


B.4 Introduction to Interaction Designer

INTERACTION DESIGNER
Interaction Designer is Interactive Intelligences graphical application generator. Interaction
Designer is the tool for viewing, debugging and writing the programs (handlers) that control the
various interaction processing behaviors within the Interaction Center.
Interaction Designer offers hundreds of tools that perform various functions, including:
Access a database
Send an email message
Send a fax
Transfer a call
Integrate with a mainframe
And many others

By logically linking these tools together in a handler, you can create almost unlimited functionality. For
example, the out-of-the-box remote voice mail retrieval functionality is comprised entirely of handlers.

THE INTERACTION DESIGNER INTERFACE

Interaction Designer (ID) is an all-inclusive development environment that:


Provides a unique editing window, where programming logic is designed.
Provides the tools (or programming statements) necessary for creating the logic.
Displays the tools in a design palette that acts as a toolbox. Using the drag and drop capability,
tools can be easily added to the editing window when creating handlers and connected together
to create the flow of the program.

B-13Appendix B 2017, Interactive Intelligence, Inc.


After creating the logical steps and specifying the flow of the handler logic, the handler must be
published. The publishing process translates the handler into computer executable language. A
common programming term for this is compiling; we use the term publish. The published handler
is the program that will perform some action, determine the outcome of a condition, route the
interaction a certain way, and so on.

INTERACTION DESIGNER MENUS

ID has a menu bar similar to other Windows-based applications. Many menu selections have
corresponding toolbar buttons. Menu items that have an associated toolbar button display the
toolbar button icon beside the menu choice. The ID menu bar displays the following menus:
File Menu
Edit Menu
View Menu
Layout Menu
Utilities Menu
Window Menu
Help Menu

FILE MENU

The File menu offers the following commands:


New Creates a document.
Open Opens an existing document.
Close Closes an opened document.
Save Saves an opened document using the same file name.
B-14Appendix B 2017, Interactive Intelligence, Inc.
Save As Saves an opened document to a specified file name.
Download Handler From Server Downloads one or more handlers from the IC server to a
selected directory.
Print Prints a document.
Print Preview Displays the document on the screen as it would appear printed.
Print Setup Selects a printer and print parameters.
Properties Allows you to edit the handler description.
Export to XML Generates a text file of the current handler in XML format.
Change Initiator Changes the Initiator for the current handler, or allows you to select an initiator
for a new handler.
Publish Publishes a handler to the Interaction Center server.
Debug Immediately Launches a debugging session for the currently published version of the
active handler.
Generate an .i3pub file Creates and saves an intermediate publish file.
Import Global Variables Opens the Global Variables Manager window to import variables on the
IC server into the present handler.
Exit Exits Interaction Designer.

EDIT MENU

The Edit Menu offers the following commands:


Cut Deletes data from the handler and moves it to the Clipboard.
Copy Copies data from the handler to the Clipboard.
Paste Pastes data from the Clipboard into the handler.
Delete Deletes the selected object from the handler.
Select All Selects all steps in the active handler window.
Preferences Allows you to set default behaviors for Interaction Designer.

B-15Appendix B 2017, Interactive Intelligence, Inc.


VIEW MENU

The View menu determines which parts of the Interaction Designer window are displayed. You
cannot hide the Handler area.

LAYOUT MENU

B-16Appendix B 2017, Interactive Intelligence, Inc.


The layout menu provides facilities for aligning nodes within a handler, toggling the display of
gridlines on the handler background, zooming in and out on the handler, and ways to align nodes
along the edges of a node.
Grid The Grid menu item toggles the display of the grid on the background of the currently
displayed handler. While it can be useful for visually aligning steps, there is no Snap To Grid
functionality present in 2.4. The grid is for display purposes only.
Go The Go menu provides a way to move a page or a line at a time in any direction, or jump
back to the upper left of the currently displayed handler.
Zoom This menu lets you choose a pre-defined zoom level to view a handler. The smaller the
number, the smaller tool steps, and links appear on a handler. The In menu item changes the
zoom so that everything appears larger. Consequently, the Out menu item will change the zoom
so that everything appears smaller.
Align Selected Steps The ability to align selected nodes along a particular edge becomes
available when you have selected two or more tool steps on a handler. Steps will be aligned along
the specified edge of the primary selected step as indicated with a solid blue border.
Resize Selected Step(s) to Label This menu item is selectable when you have selected a step or
steps. It resizes the selected step or steps so that all of the text within the step label is visible.

UTILITIES MENU

The Utilities menu offers the following commands:


Quick Jump Opens the QuickJump palette and allows you to populate it with all steps, just
steps that have no entry path, just steps that have no exit path, or to clear the QuickJump
palette. From the QuickJump palette, you can double- click a step name to move focus to that
step in the Handler area of the window.
Manage Handlers Opens the Manage Handler notebook allowing you to activate and
deactivate primary and monitor handlers.
Debug Handlers Opens the Debug Handler dialog box which allows you to select a handler or
handlers to debug.
Stored Procedures Displays and allows you to edit the definition of a stored procedure. This
is either the definition as passed in by the ODBC driver, or the definition that you have modified
previously in this dialog box. Use this dialog to augment a stored procedure definition if the
ODBC driver did not pass in a complete definition.
View Dependencies Opens the Dependencies notebook where you can view dependencies of
various objects (that is tools). You can view the information either by what objects are used by a
handler or by what handlers use the object.
Import Prompts and Strings Allows you to import a list of .wav files and their transcripts.
Export Prompts and Strings Allows you to export the prompts from the active handler. Each
prompt is exported as a separate .wav file.

B-17Appendix B 2017, Interactive Intelligence, Inc.


WINDOW MENU

The Window menu offers the following commands:


New Window Creates a new window that views the same document.
Cascade Arranges windows in an overlapped fashion.
Tile Arranges windows in non-overlapped tiles.
Arrange Icons Arranges icons of closed windows.
Handler1, 2, and so on Sets focus to the selected handler.

HELP MENU

The Help menu offers the following commands:


Help Topics Offers you an index to Interaction Designer topics on which you can get help.
About Displays system information about IC and the operating system.

B-18Appendix B 2017, Interactive Intelligence, Inc.


THE SCREEN MAP

There are several areas in the Interaction Designer interface that require more explanation at
this time:
Standard Toolbar
Palette Toolbar
Layout Toolbar
Handler Area
Design Palette
Messages palette
Debug Palette
Variables Palette
Quickjump Palette

Each of these areas is described in detail on the following pages.

TOOLBARS
Standard Toolbar The standard toolbar provides many typical functions. These functions are also
found in the File menu or Edit Menu.

B-19Appendix B 2017, Interactive Intelligence, Inc.


Palette Toolbar The palette toolbar provides buttons that toggle the display of palettes in the ID
window. These functions are also found in the View menu.

Layout Toolbar The layout toolbar provides a button to toggle the grid display, a list box that lets
you zoom in or out on the handler using predefined settings, and buttons that allow you to quickly
align selected steps. These functions are also found in the Layout menu.

HANDLER AREA

The handler area displays currently open and non-minimized handlers. Use the Windows menu to
determine how to display the open handlers or to choose the handler to display. The grid can be
used to align the handler steps and can be turned off under the Layout menu.
As you can see, a handler consists of steps connected together. These steps are sequentially
processed to form the logic of the handler.

B-20Appendix B 2017, Interactive Intelligence, Inc.


DESIGN PALETTE (TOOLS PAGE)

The Design palette has two pagesthe Tools page and the Subroutines page.
Tools Page Use the Tools page to insert steps into a handler. Tools provide the functionality of the
handler. The Tools page is a virtual tool chest providing tools specific to handler development. Tools
allow the handler to:
Create variables and/or assign a value to a variable
Test conditions
Connect to and read from a database
Place calls
Play a .wav file
Test a condition and branch accordingly
And perform hundreds of other useful functions

A step is an instance of a tool in a handler. Most tools have parameters that must be completed
before the step is functional. A handler is made up of multiple steps that have been connected
together to form the logic of the handler. The steps will be completed in a sequential order.

DESIGN PALETTE (SUBROUTINES PAGE)

Subroutines Page Use the Subroutines page to insert a subroutine call into a handler.
A subroutine tool will exist for every handler created with a subroutine initiator.
Each page of the subroutine palette contains a group of related subroutine tools. These groups
are called categories.
The categories and labels for the subroutine tools are created when subroutines are published.
A subroutine tool will not appear in the Design palette until the subroutine has been published.
B-21Appendix B 2017, Interactive Intelligence, Inc.
MESSAGES PALETTE

The Messages Palette contains two pagesthe Handler Messages page and the General
Messages Page.
Handler Messages If a condition exists within the handler that would prevent it from being
published, a message will be displayed in the Handler Messages page along with the Step ID to which
the message pertains. Double-clicking on the message will shift the design windows view to focus on
the relevant step and select that step.
General Messages The messages listed here describe problems that pertain to Interaction
Designer but not to any specific handler. These errors can relate to the COM API, loading libraries,
loading subroutines, and so on

DEBUG PALETTE

The debug palette contains four tabs for viewing the activity of a handler during a debug session.
Watch Variables This window will display the values of watch variables throughout the debugging
session and will also give you the option to have the handler pause whenever the value of one of the
watched variables changes.
Step Variables When execution is paused on a step, users can click the Step Variables tab in the
Debug Palette and Designer will show the variable values for all variables used by the currently
displayed executing step.
Handler Variables When execution is paused on a step, users can click the Handler Variables tab in
the Debug Palette and Designer will show the current values for all variables in the currently
displayed handler.
Call Stack This window contains the call stack for the currently executing handler. The information
in the call stack is in the format (step ID) Handler name. Users can select entries in the window to
view other handlers that are in the call stack. The calling step is highlighted with a dashed line. The
currently executing step will have a solid line around it.

B-22Appendix B 2017, Interactive Intelligence, Inc.


VARIABLES PALETTE

The Variables Palette provides information about the variables that are currently defined within the
selected handler.
Handler authors can right-click on variables shown in the variable bar to display the following menu:

List Steps That Use This Variable Populates the QuickJump palette with steps in the current
handler that reference the selected variable. This option opens the QuickJump Palette if it is not
already open.
Add Selected Variable(s) to Watch Variables Tab Populates the Watch Variables page of the
Debug Palette with the selected variable or variables. This selection is only available when the
current handler is in debug mode.
Add Variable Opens the Declare Variable dialog in which you can create a variable and assign
it an initial value. This selection is not available in debug mode.
Rename Variable Opens the Rename Variable dialog in which you can change the name of an
existing variable. This selection is not available in debug mode.
Delete Selected Variables(s) Deletes the selected variable or variables. This selection is only
available if the selected variable or variables are not referenced in the current handler. This
selection is not available in debug mode.
Set Initial Value Opens the Initial Value dialog in which you can assign a literal initial value.
This selection is not available in debug mode.

B-23Appendix B 2017, Interactive Intelligence, Inc.


When assigned from the Variables Palette, initial values can only be literal values, not variables, or
expressions containing variables.
Clear Initial Value(s) Clears the initial value for the selected variable or variables. This
selection is not available in debug mode.
Import Global Variables Opens the Global Variable Manager dialog in which you can create
new global variables or import an existing global variable into the current handler. Global
variables are only available on the IC server on which they are created. This selection is not
available in debug mode.
Because the global variable is locked throughout the duration of a handler instance, write
subroutines that read/modify the contents of global variables to minimize the time a global
variable is locked.
Select All Selects all the variables in the Variable Palette window.
Select All Unused Selects all variables that are not referenced in the current handler.

QUICK JUMP PALETTE

The QuickJump Palette provides a way for you to quickly find a step in a handler. By double-clicking
the Step Label in the palette, ID will select that step and set focus to the portion of the handler that
contains the step.
You can set options for the display within the QuickJump palette in the Utilities menu.

Review Questions
Complete the review questions for this module in your study guide.

Labs
There are no labs associated with this module.

B-24Appendix B 2017, Interactive Intelligence, Inc.