• Contents

Overview of Building and Modifying Handlers and Subroutines

This section offers an overview of the entire process of building and editing handlers and subroutines. You should read this before you begin using Interaction Designer to build or modify handlers and subroutines. This section contains the following subsections:

  • Overview of Steps

  • Step 1: Research

  • Step 2: Design

  • Step 3: Building

  • Step 4: Activating

  • Step 5: Testing

  • Step 6: Promoting   

Overview of Steps

The process of building handlers can be broken down into six steps.

Step one: Research. You should be familiar with the handlers and subroutines currently running on your system.

Step two: Design. Map out the functionality you plan to build, and figure out how it will run with the other handlers and subroutines.

Step three: Building. Begin creating and linking steps to perform the new functionality.

Step four: Activating. When you finish building the handler or subroutine, you must compile and move it to the IC server using the automated Publish process. Handlers and subroutines are published through Interaction Designer.

Step five: Testing. Test the handler on your live system or on a second system you've set up for testing purposes.

Step six: Promoting. If you are not already using the handler on your live system, activate the handler.

Step One: Research

The first step in building handlers and subroutines is research. You must be familiar with the handlers and subroutines currently being used on your CIC server. You need to know if the handler or subroutine you're planning can be integrated into a currently running handler. Also, find out if you need to build a new handler or subroutine, or modify an existing one. You cannot build a new handler or subroutine if you don't spend some time looking at the existing handlers.

There are several places you can look for information on the existing handlers. First, look at the contents of the Handler Help menu. Many of the handlers and subroutines shipped with CIC are documented under Handler Help. This documentation summarizes the functionality of the handlers and subroutines, and can help you see where you might want to make customizations.

Also, review the reference and procedural topics in this online help system. The tool documentation in the Reference section 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.

Step Two: Planning

Once you are familiar with how the handlers and subroutines are working on the CIC server, begin planning how to build in the new functionality. Decide how the new functionality will be implemented. Review the following scenarios when making your decision.

When should I modify an existing handler or subroutine?

In many cases, modifying an existing handler is the best way to implement new functionality. In a simple example, you might want to add a new key-press option for callers using your IVR (Interactive Voice Response) system. In this case, adding new functionality only involves recording a new prompt, adding a condition to a Selection step, and adding a few other steps to your existing IVR handler. You don't need to write a whole new subroutine or handler to add this simple functionality. If you only need small changes or additions to the CIC functionality, consider small modifications to your handlers or subroutines.

If you decide to modify an existing handler or subroutine, we recommend that you only do so using the customization points provided. Customization points ease future upgrades. Modifications made outside these customization points may be overwritten when a hotfix or service release is installed. Modifying handlers outside the designated customization points may also cause undesired behavior in CIC.

When should I build a new handler or subroutine?

If you are planning a significant addition or change in functionality, you probably need to build a new handler or subroutines. In most cases, you should build a subroutine. A handler will start when an event occurs on the server to start that handler. Most of the events that occur on the CIC server already have a handler associated with them. Unless you are adding third-party products that generate their own unique events, you build a subroutine.

An example of a piece of third-party equipment that might generate a unique event is some kind of machine monitor. Suppose 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 CIC and start a handler designed to watch for an alarm event.

Whether you decide to build a handler or a subroutine, map out the new functionality on a whiteboard. 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.

Step Three: Building

Once you've mapped out the functionality and decided to implement the functionality, you're ready to start modifying or building your handler or subroutines in Interaction Designer. Use Interaction Designer to add new steps and modify existing steps. For help on a particular step, click the help button on its properties page, or you can select a tool on the tool 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 online help. Finally, look at how steps are used in other handlers and subroutines.

You do not need to deactivate a handler before you begin editing because any changes you make to a handler or subroutine do not take effect until you publish the handler or subroutine and activate that handler or subroutine using the Manage Handlers notebook.

Step Four: Activating

Once you have finished building or modifying a handler or subroutine, you need to publish it so that your changes take effect. Publishing a handler is the automated process of converting the handler to Java code, compiling that code with a Java compiler, and placing the compiled code on the CIC server. During the publishing process, you may be notified of errors in the handler or subroutine. These errors might result from unfilled parameters, invalid variable names, or other problems. Refer to the publishing online help for advice on successful publishing. You may also need to consult the documentation that accompanied the Java compiler.

Subroutines must be published before they can be called from other handlers and subroutines. Once you have published a new subroutine, a new subroutine tool appears on your subroutine palette. Use this tool to create a new step in the handler or subroutine that calls the new subroutine.

There are certain situations where you may not want to publish your handlers or subroutines to the same server where you created them. To accomplish this, an intermediate publish file is generated and saved to a specified location, where it can then be moved to the desired server and the publishing process completed.

When a handler or subroutine is first published, you have the option to have it made active immediately. If you choose not to do this, or if the handler has been imported from another server or previously made inactive, you will need to activate it in the Manage Handlers notebook before it can be used in CIC.

Step Five: Testing

After you've published your handler or subroutine, either to a test server or the production server, test the functionality you've built.

Step Six: Promoting

If you've not already set a handler to active using the Manage Handler notebook, you should do so. This activates the new functionality.

Handler Best Practices

Publish a handler or subroutine