Stand-Alone Installation

1. Unzip the Distribution

If you haven't already. You don't have to install OrderlyCalls on the same machine as your Asterisk (TM) server (though you can if you like).

> unzip OrderlyCalls.zip

We'll call the directory this creates ORDERLYCALLS_HOME.

2. Install Java 5.0

OrderlyCalls requires Java 5.0 (=1.5) or later to run. You can get it from java.sun.com

To run OrderlyCalls, you'll need a JRE or JDK Java Virtual Machine.

To compile OrderlyCalls, you'll need the JDK installed.

OrderlyCalls uses classes from the J2EE Servlet specification for web deployment. For compilation, OrderlyCalls needs access to these classes. If you already have a J2EE JDK installed, you can link with JAVA_HOME/lib/j2ee.jar. If you have a standard J2SE JDK installed, the OrderlyCalls compilation script will download servlet-api.jar (part of Tomcat) for you in order to compile.

J2EE classes are not necessary to run OrderlyCalls in a stand-alone environment.

3. Install Ant (Optional).

This distribution of OrderlyCalls contains precompiled classes. If you intend to write your own applications, or wish to recompile, you'll need Apache Ant to do your own compiling.

4. Install the example sounds.

The example OrderlyCalls applications use sounds included in this distribution. You need to install them on your Asterisk server.

> cd /var/lib/asterisk/sounds
> tar -xvzf /path/to/OrderlyCallsSounds.tar.gz

This will create a directory inside your Asterisk sounds directory called OrderlyCalls.

5. Set up your environment

Edit ORDERLYCALLS_HOME/setenv.bat (Windows) or ORDERLYCALLS/setenv.sh (Unix) to reflect your local environment. Once you've made the necessary edits, you should run the scripts.

Windows:
> cd \path\to\OrderlyCalls
> notepad setenv.bat
> setenv

Unix:
> cd /path/to/OrderlyCalls
> vi setenv.sh
> chmod 755 setenv.sh
> . ./setenv.sh

6. Compile the Distribution (Optional)

This will cause servlet-api.jar to be downloaded to the lib directory, and will compile the classes and generate Javadoc documentation.

> ant

7. Configure Asterisk to use AGI

Add the following lines to /etc/asterisk/extensions.conf, inside a context you can reach with your phone.

exten => 1000,1,Answer
exten => 1000,2,agi(agi://127.0.0.1)	; edit IP address as appropriate
exten => 1000,3,Hangup
exten => 1000,4,Playback(OrderlyCalls/message)
exten => 1000,5,Hangup

This configures Asterisk for use with the OrderlyQ example application. Make sure you reload extensions.conf when you've finished.

8. Launch OrderlyCalls

This assumes you've got orderlycalls.jar in your classpath, and/or you're in the the ORDERLYCALLS_HOME directory.

> java com.orderlysoftware.orderlycalls.OrderlyCalls

This will launch OrderlyCalls with the default example application, which is a demonstration of OrderlyQ (also from Orderly Software).

9. Test Your OrderlyCalls AGI Installation

Dial extension 1000 with your phone. You should hear a voice telling you you're being held in a queue, with an estimated wait time of five minutes.

Hang up and call back after a couple of minutes. You'll be given an updated wait time.

After the wait time has elapsed, you'll be at the front of the queue. Call back once more to check that your number is recognised.

10. Configure Asterisk to use Manager (Optional)

If you want to use the Manager functionality, you'll need to configure Asterisk.
Add the following lines to /etc/asterisk/manager.conf:

[OrderlyCalls]
secret=changeMe
permit=127.0.0.1/255.255.255.0		; Edit IP address appropriately.
read = system,call,log,verbose,command,agent,user
write = system,call,log,verbose,command,agent,user

Make sure you do an Asterisk reload.

11. Configure OrderlyCalls to use Manager (Optional)

Edit ORDERLYCALLS_HOME/OrderlyCalls.xml, and uncomment the ManagerClient tag and child tags.

You'll need to change the host attribute to reflect your local environment.

You should ensure that the password matches the 'secret' you entered in the previous step.

12. Test Your OrderlyCalls Manager Installation (Optional)

Restart OrderlyCalls (press CTRL-C to stop the server), and dial extension 1000 again. As the demo runs, you should see Manager Events appear in the OrderlyCalls log.

You might also want to try out the other example application. Edit OrderlyCalls.xml and change the processorClass attribute of the AGIServer tag to

com.orderlysoftware.orderlycalls.examples.ExampleProcessor

Next, restart OrderlyCalls, and call extension 1000 again.

This time you'll be prompted to enter your office code (enter any four-digit number). The number will be read back to you and the call will end. Ten seconds later, the system will call you back and play you a message.

Servlet Container (Tomcat) Installation

These instructions assume you've already completed the Stand-Alone installation.

1. Install Tomcat

Download and install Tomcat from jakarta.apache.org, if you haven't already.

We'll call the top-level Tomcat directory TOMCAT_HOME.

OrderlyCalls can work inside any J2EE-compliant servlet container, so you may choose another. These installation instructions assume you're using Tomcat.

2. Install OrderlyCalls Library

Copy ORDERLYCALLS_HOME/orderlycalls.jar into TOMCAT_HOME/common/lib

This ensures that OrderlyCalls functions and classes are available to all your servlet contexts (.war files).

Restart Tomcat when you're done so it can find the new classes.

3. Install OrderlyCalls Web Application

Although Tomcat now has access to the OrderlyCalls classes, it does not yet know how to start and configure your services. To do this, copy ORDERLYCALLS_HOME/orderlycalls.war into TOMCAT_HOME/webapps. This will create a new context, orderlycalls

The new context contains a copy of the OrderlyCalls.xml file from your ORDERLYCALLS_HOME (so if you've made edits, you may want to recompile). When the context is started, OrderlyCalls finds this copy and initialises the services, which can then be accessed from all contexts.

You can access the default web applications that are part of orderlycalls.war at

http://localhost:8080/orderlycalls

Once you've logged in, you can control your services, and manage the example OrderlyQ application.

Please see the Developer's Guide for information on using OrderlyCalls with your own web applications.