TSAPI Exerciser Scripting Instruct Issue2

Editor: J . Gresh 2009 Avaya Inc. All Rights Reserved.
1 of 19
Date: 12/15/2009 CID: 144440

Avaya Aura Application Enablement Services
TSAPI Exerciser Scripting Instructions Issue 2.0

Abstract

The TSAPI Exerciser included in the Application Enablement Services TSAPI
Windows Software Development Kit includes a script interpreter. The script
interpreter may be used by TSAPI application developers to drive test scenarios.
This paper provides describes the scripting language for the TSAPI Exerciser.

Editor: J . Gresh 2009 Avaya Inc. All Rights Reserved. 2 of 19
Date: 12/15/2009 CID: 144440
Table of Contents
1. INTRODUCTION..................................................................................................................... 3
2. OVERVIEW .............................................................................................................................. 3
3. RUNNING SCRIPTS ............................................................................................................... 3
4. SCRIPT FILE COMMANDS .................................................................................................. 3
5. SCRIPT OPCODES AND OPCODE-SPECIFIC FIELDS .................................................. 5
5.1 CHANGE DEVICE .............................................................................................................. 6
5.2 DEFINE ................................................................................................................................ 7
5.3 ELSE ..................................................................................................................................... 7
5.4 ENDIF ................................................................................................................................... 8
5.5 IFDEF/IFNDEF .................................................................................................................... 8
5.6 IGNORE ............................................................................................................................... 8
5.7 ITERATE .............................................................................................................................. 9
5.8 MANUAL ............................................................................................................................. 9
5.9 SEPARATOR ....................................................................................................................... 9
5.10 WAIT ................................................................................................................................ 10
6. WAIT CONDITION EVENTS .............................................................................................. 11
7. SAVE FIELDS ........................................................................................................................ 12
7.1 MESSAGE PROCESSING ................................................................................................ 13
7.2 POTENTIAL PITFALLS ................................................................................................... 14
7.2.1 Outstanding Confirmation Events................................................................................ 14
7.2.2 Event Ordering ............................................................................................................. 15
7.2.3 Call Cleared Events in Conference Scenarios ............................................................. 15
7.2.4 Save Field Behavior ..................................................................................................... 16
7.2.5 Save Field Initialization ............................................................................................... 16
7.2.6 Wait Conditions and Save Fields ................................................................................. 16
8. SAMPLE SCRIPTS ................................................................................................................ 16
8.1 SIMPLE CALL ................................................................................................................... 16
8.2 CONFERENCE CALL SCRIPT ........................................................................................ 18

Date: 12/15/2009 CID: 144440
1. Introduction
To facilitate regression testing, the TSAPI Exerciser includes a script interpreter with the ability
to read and execute instructions contained in a script file. The script interpreter is designed to
run in a single user environment so that input from other activities do not confuse script
operations. It is included in the SDK on an "as is" basis in the hope that it may be of use to
others.
2. Overview
A script file allows a user to execute a file containing a series of exerciser-type commands. Each
command line contains an opcode indicating the type of action to be executed. Once this action
is executed, the script interpreter halts until an event specified by the user occurs. While the
script interpreter is waiting for this "wakeup event", data can be extracted from incoming
messages to be used in subsequent commands.
The script interpreter has been designed to keep the processing simple. It is up to the script
writer to construct the script so that it always does what is needed; the script interpreter does not
attempt to decide which data is to be used and which is not. This document attempts to provide
enough information on how the interpreter works so that script writing is as straightforward as
possible.
Sample scripts and the resulting output are included throughout this document. The two are
interwoven with the script command on the right side of the page and the output at the left
margin. Information contained in the output is sometimes abbreviated to make the example
clearer.
3. Running Scripts
You must install the Avaya Application Enablement (AE) Services TSAPI Windows client and
the Avaya AE Services TSAPI Windows SDK in order to run the TSAPI Exerciser.
To run a script from the TSAPI Exerciser:
1. Select Run | Start Exerciser Session.
2. Enter valid values in the Start Exerciser Session dialog box and click OK to open a stream.
3. Select Run | Open Script File.
4. Use the Open file dialog box to select which script you would like to run.
5. Select Run | Run Script. When prompted, click on Yes to confirm that you would like to
run the script.
4. Script File Commands
The general format of a script command within a script file is
opcode <opcode-specific fields><wait-condition><error-treatment><save1><save2>
where command fields are separated by white space. Only the opcode and the opcode-specific
fields are required. The remaining fields have default values. However, if a command includes

Date: 12/15/2009 CID: 144440
an optional field, then all of the fields before that field must be provided, even if the default
values are to be used. Failure to do this results in unpredictable behavior.
Table 1: Script Command Fields

Field Description
opcode The opcode field specifies which command the script interpreter should
run. The opcodes and opcode-specific fields are described in the next
section.
wait-condition The wait-condition field tells the script to stop processing until a certain
event occurs.
Most opcodes have a default wait value, "WAIT_DEFAULT", so this
needs to be set only when the default does not do what is desired or if
subsequent fields on the command line are used. In all cases, a wait
timer is set to ensure that the script does not hang indefinitely. If this
timer expires, the script performs the specified error treatment.
error-treatment The error-treatment field tells the script interpreter what to do if it
encounters an error (e.g., the wait timer expires, a CSTA or ACS failure
occurs, or a script error is encountered).
The two allowed values are "stop" and "continue".
The default value for this field is stop.
save1 Once a call is initiated, further requests to control the call must use the
correct connection ID or call ID. Since this information is only known
when the call is created, the script writer must be able to save specific
information returned in confirmation messages or unsolicited events and
to access it in later requests.
The interpreter maintains an array of 16 connectionID elements which
are identified by the tags ID1, ID2, ... ID16. By using these tags in this
field, connection ID data can be saved in one or more of these array
elements. (A single connectionID may be saved in multiple array
elements by 'OR'ing the tags for those array elements together.)
The script interpreter determines which connectionID is saved in this
field based on the confirmation event or unsolicited event. Generally
speaking, the save1 field is used to save the connectionID of the
originating device.
The default value for this field is 0.
save2 This is a second array tag used to indicate where data is to be saved.
(See save1.)
As with the save1 field, the script interpreter determines which
connectionID is saved in this field based on the confirmation event or
unsolicited event. Generally speaking, the save2 field is used to save the
connectionID of the terminating device.
The default value for this field is 0.

Date: 12/15/2009 CID: 144440

Each command must appear on a single line; commands cannot be split across multiple lines.
Field values are case insensitive. Scripts may include upper and/or lower case characters in any
combination for any field value.
For each field within a command, the script writer need specify only enough characters to
uniquely identify the field value; it is not necessary to completely spell out every field value.
However, doing so may improve readability.
Scripts may contain comments. If a "#" sign is placed anywhere on the command (outside a text
string), all information following the "#" is treated like a comment.
A field requiring text must be enclosed by quotes. For example:
separator "Test Case 3.4"
5. Script Opcodes and Opcode-Specific Fields
The script interpreter supports most of the CSTA requests supported by the TSAPI Exerciser.
Several additional opcodes are available for script control and the ability to perform manual
functions.
The supported opcodes and the required arguments are listed in Table 2 and Table 3 below:
Table 2: CSTA Service Opcodes

CSTA Service Opcode Opcode-Specific Fields Optional Fields
cstaAnswerCall() answer connectionID wait-condition
error-treatment
save1
cstaConferenceCall() conference held-connectionID
active-connectionID
wait-condition
error-treatment
save1
cstaClearCall() clear_call callID wait-condition
error-treatment
save1
csta-ClearConnection() clear_conn connectionID wait-condition
error-treatment
save1
cstaHoldCall() hold connectionID wait-condition
error-treatment
save1
cstaMakeCall() makeCall calling-deviceID
called-deviceID
wait-condition
error-treatment
save1
save2
cstaMonitorCallsVia-
Device()
monitor_callVD deviceID
call-filter
wait-condition
error-treatment
save1
cstaMonitorDevice() monitor_dev deviceID
call-filter
wait-condition
error-treatment
cstaMonitorStop() monitor_stop deviceID wait-condition
error-treatment
cstaRetrieveCall() retrieve connectionID wait-condition
error-treatment
save1
cstaSetDoNotDisturb() set_dnd deviceID on|off wait-condition
error-treatment

Date: 12/15/2009 CID: 144440
CSTA Service Opcode Opcode-Specific Fields Optional Fields
cstaSetForwarding() set_fwd deviceID
forward-to-deviceID
on|off
wait-condition
error-treatment
cstaSetMsgWaitingInd() set_mwi deviceID on|off wait-condition
error-treatment
cstaTransferCall() transfer held-connectionID
active-connectionID
wait-condition
error-treatment
save1
Table 2 contains the opcodes for CSTA services. The opcode-specific fields often include:
a device ID, which is usually known when writing the script; or
a connection ID, (call ID, device ID and device type), which is only known at run time.
A connectionID must be retrieved from an event message and saved for later use. It is up to
the script author to determine which event message will provide the connectionID and to take
the appropriate steps to save that information. This is discussed in more detail in the "Save
Fields" section.
Table 3: Script Control Opcodes

Opcode Opcode-Specific Fields Optional Fields
change_device indexID deviceID
define variable-name value
else
endif
ifdef variable-name
ifndef variable-name
ignore on|off
iterate count
manual text wait-condition
error-treatment
save1
save2
separator text
wait ms-delay wait-condition
error-treatment
save1
save2

Table 3 contains additional opcodes to control script processing. The use of each is described
below.
5.1 Change Device
Syntax:
change_device indexID deviceID
Description:
The "change device" command replaces the device ID within a saved connection ID with
the device ID specified on the command line. The indexID parameter specifies which of

Date: 12/15/2009 CID: 144440
the saved connectionIDs should be updated. More than one array element can be
overwritten by 'OR'ing the identifiers together.
Example:
change_device ID2 4441
5.2 Define
Syntax:
define variable-name value
Description:
A "define" statement is used to associate a variable name with a value, which may be an
expression. This variable name, preceded by a "$", can then be used throughout the
script wherever the expression would have been used.
Each variable name can be up to fifteen characters long and can expand to a maximum of
63 characters. A script may contain a maximum of 32 define statements.
Examples:
define ext1 55851
define ext2 55852
define acd2 55042
define vdn1 55058
define badext 9999
define tac_ext1 814605851
define tac_ext2 814605852
Once defined, the variable name may be used in the script as shown below. Defines makes it
much easier to change deviceIDs if the script is to be run on different PBXs with different
extensions.
monitor_dev $ext2 0x000 wait_default stop
makecall $ext1 $ext2 wait_default stop ID2
Text strings can include defines instead of the actual device ID:
If the variable reference is separated from the rest of the text by spaces, use the normal
notation (e.g. $tac_ext1).
If something other than a space immediately follows or precedes the variable reference, the
reference must be set off by braces (e.g. ${ext2}).
In the example below, the $ext1 variable reference requires braces because it is followed by a
period.
manual "Call $tac_ext1 from ${ext2}." DELIVERED stop 0 ID2
5.3 Else
See Ifdef/ifndef.

Date: 12/15/2009 CID: 144440
5.4 Endif
See Ifdef/ifndef.
5.5 Ifdef/ifndef
Syntax:
ifdef variable-name
ifndef variable-name
Description:
A script can be made to execute (or not execute) a section of code based on the value of a
parameter defined in the script. The value of this variable cannot change during script
processing. The usage of the "ifdef", "ifndef", "else" and "endif" opcodes is
similar to that for the "C" preprocessor directives #ifdef, #ifndef, #else, and
#endif.
Example:
define MAN_MODE 1

ifdef MAN_MODE
manual "Call from $ext1 to ${ext2}, hold call at $ext2
and answer call at ${ext2}" ESTABLISHED stop 0 ID4
else
makecall $ext1 $ext2 DELIVERED stop 0 ID4
hold ID2 wait_default stop
answer ID4 ESTABLISHED stop
endif
conference ID2 ID4 wait_default stop ID2
clear_call ID2 wait_default stop

When MAN_MODE is defined, the script prompts the user to perform the instructions between the
"ifdef" and the "else". If the definition is removed, the script executes the "makecall",
"hold" and "answer" commands - the equivalent of the manual operations.
[The "manual" command must actually appear one line; it is broken into two lines here for
readability.]
5.6 Ignore
Syntax:
ignore on
ignore off
Description:
An entire section of the script can be skipped out by using the "ignore" opcode. Place
the command "ignore on" at the beginning of the section to be skipped out and
another command "ignore off" at the end of the section. The script ignores all lines
between the two statements.

Date: 12/15/2009 CID: 144440
5.7 Iterate
Syntax:
iterate count
Description:
The "iterate" command causes the entire script to be executed the number of times
indicated by the count parameter. This command should be the last command in the
script; if it is placed anywhere else in the script, the script stops executing when it reaches
the "iterate" command and starts over at the beginning. Commands placed after the
"iterate" command are not executed. The completion of an iteration is marked by a
line on the screen giving the iteration count.
When starting a new iteration, the interpreter closes the script file, reopens it and clears
all local variables associated with the script, including monitors set on a device and the
associated cross reference ID. As a result, it has no knowledge of monitors set up or calls
placed on prior passes even though these monitors still exist and the calls are still active.
Resources should be cleaned up prior to the "iterate" command.
5.8 Manual
Syntax:
manual text wait-condition error-treatment save1 save2
Description:
The "manual" command creates a message box and prints a user supplied text string
inside it. The user is then prompted to "Hit 'enter' when done". The text string can be
used to give instructions about manual operations that must be performed before the
script can continue. By striking the enter key when the action is complete, the flow of the
script is controlled. Striking the 'cancel' key causes the script to execute the specified
error-treatment.
Users should be careful about the timing of the enter key. If the key is struck before the
manual action has completed, some devices may not be in their proper state, causing
subsequent script commands to fail.
The text string on the command line may not exceed 99 characters and must be
surrounded by double quotes, ("), on the command line.
5.9 Separator
Syntax:
separator text
Description:
The "separator" command provides a way to divide the output in a meaningful way.
When this opcode is encountered, a line of stars is printed, plus the text string, if any,
supplied by the user. The user supplied text string cannot exceed 99 characters. The text
string must be enclosed by double quotes, ("), on the command line.

Date: 12/15/2009 CID: 144440
One use of this opcode is to separate the output from different test cases. For example:
CONFIRM Clear Connection
EVENT Conn Cleared Call ID: 217 Device ID: 55851 CrossRefID:1
Releasing Device: 55851
=> ***************************** Test Case 2.3 **********************
REQUEST Monitor Device 55852
CONFIRM Set Monitor Cross Reference ID: 2
REQUEST Make Call Calling Dev: 55851 Called Dev: 814605852
5.10 Wait
Syntax:
wait ms-delay wait-condition error-treatment save1 save2
Description:
The "wait" command allows the user to stop script execution for a short period of time.
This can be used to flush the system of incoming messages before proceeding with the
next script instruction. The script can be resumed after either a set time interval (the "ms-
delay") expires or after a certain message, as specified by the "wait-condition", is
received. (See below for more information about "wait" conditions.)
The command cannot wait for both a delay and an wait for an event; if the ms-delay is
non-zero, then the "wait-condition" is ignored. If the ms-delay is zero, then the "wait-
condition" is used. There is no default value for the wait-condition.
The delayl is measured in milliseconds. If the save fields are included, messages that
arrive before the delay expires or the wait condition occurs are examined for data.
Examples:
Two examples are given below.
In the first example, the "monitor_stop" request occurs before the connection cleared
events arrive. Although innocuous in this example, this behavior can cause problems.
In the second example, the script waits for three seconds (3000 ms) before continuing.
This allows enough time to elapse so that the connection cleared events can be processed
before the "monitor_stop" request.
In both examples, the script output is displayed in abbreviated form on the left. The
script commands are displayed on the right at the point that the command executes.
Example 1:
clear_call ID2 wait_default

REQUEST Clear Call Call ID: 15
CONFIRM Clear Call
EVENT Conn Cleared Call ID: 12 Dev ID: 4441

monitor_stop 55850

REQUEST Monitor Stop Cross Ref ID: 1010
EVENT Connection Cleared Call ID: 12 Device ID: 4442
CONFIRM Monitor Stop

Date: 12/15/2009 CID: 144440
Example 2:

CONFIRM Clear Call
EVENT Conn Cleared Call ID: 15 Device ID: 4441

wait 3000


monitor_stop 55850

6. Wait Condition Events
There are two reasons why actions requested by one command must complete before processing
of the next command begins:
First, information needed in subsequent requests is only available in confirmation messages
and unsolicited events received as a result of the first action.
Second, there is no guarantee that the call, or connection on the call, is in the necessary state
until the specific event report is received.
The "wait-condition" field on the command line allows the script author to indicate which
incoming message should cause the script interpreter to continue processing. The allowed values
for the wait condition event are:

call_cleared
conferenced
confirmation
conn_cleared
delivered
diverted
established
failed
held
network_reached
no_wait
queued
retrieved
service_init
transferred

These events can be OR'ed together if more than one event is acceptable.
A failure timer (60 seconds) is set each time a command is executed. If the failure timer expires
before the desired message is received, the script interpreter executes the specified error
treatment.

Date: 12/15/2009 CID: 144440
Most opcodes have an associated default event. If the command line does not contain a wait-
condition or if "WAIT_DEFAULT" is specified, the default value is used. The default values for
each opcode that supports the wait-condition field are given below:

answer established | failed
clear_call conn_cleared | call_cleared | failed
clear_conn conn_cleared | call_cleared | failed
conference conferenced | failed
hold held | failed
makecall delivered | queued | network_reached | failed
manual -
monitor_callVD confirmation
monitor_dev confirmation
monitor_stop confirmation
retrieve retrieved | failed
set_dnd confirmation
set_fwd confirmation
set_mwi confirmation
transfer transferred | failed
wait -

When possible, the default values are unsolicited events. This assumes that monitors have been
set in the script which results in these events being reported. There is no checking done by the
script interpreter to guarantee that this is true.
If an event is set as the wait event, the first event of that type received causes the script to resume
processing, even if the event is the result of an earlier command. This can cause the script to
work in unexpected ways.
If the devices on the PBX are in a known state, the script writer knows what type of messages to
expect in response to a particular request. For example, if a destination device is busy on a call
or is not administered as auto-answer, a makecall request to that device should result in a
delivered event but not an established event. If the script waits for an established event, the
failure timer will expire because no established event is returned.
If the wait condition is set to NO_WAIT, defined as "0", the script does not wait at all after
executing the opcode; it proceeds to execute the next line in the script.
7. Save Fields
Users must be able to retrieve information from confirmation and event messages in order to
control a call once the call has been initiated.
Commands like "hold" and "clear_conn" require connection IDsnot device IDsas
arguments. The optional save fields allow the script writer to save connection ID information
returned in messages for subsequent use.
Each "save" field identifies a specific entry in an array of connection IDs where this type of
information can be stored. The array contains 16 elements. Each element identifier (ID1, ID2,
....) is actually a single bit. ( ID1 =1 <<0; ID2 =1 <<1, ...) By logically ORing two identifiers
together ( ID1 | ID2 ), a save field can be used to save information in more than one array
element.

Date: 12/15/2009 CID: 144440
The actual "save" implementation evolved as scripts were written for regression testing. Two
save fields, "save1" and "save2", are needed because the "makecall" request returns two
needed pieces of information: the connection IDs of both the originating and destination
devices. Some events, like "diverted" and "service_initiated", need only one field.
In general, for commands that use two save fields, save1 is used for the device that originated
the call and save2 is used for the device that received the call.
Data only needs to be saved when it changes.
The save field parameters are the last arguments on the command line. When the command
line is parsed, the values in these fields are saved in the save1 and save2 variables. The script
interpreter extracts information from incoming messages only if the appropriate variable, save1
or save2, is non zero.
Once a field is zeroed, data in that field is protected. Some messages cause a variable to be
zeroed once data has been extracted; others don't. If the variable is zeroed, no other data can
overwrite it. If the variable is not zeroed, subsequent event reports can result in overwriting data
previously saved.
Again, the implementation depends on experience gained in writing scripts. For example, the
"delivered" event does not cause save2 to be zeroed because another "delivered" event may be
received if a call goes to a covering device.
Retrieving data from incoming messages is not always as straight forward as it may seem. The
script compiler has no way of knowing the type or number of messages that may return as a
result of executing an opcode since this can depend on the number and type of monitors set, the
state of the calling/called device at the time of the opcode execution and other activity at the
switch. For this reason, responsibility in retrieving the desired data resides with the script author.
7.1 Message Processing
The algorithm described below represents exactly what the interpreter does when it receives a
message and, hopefully, can be used to explain why a particular script behaves the way it does.
The format is a quasi-pseudo code.
When retrieving data from the message, (Section B), the type of message is used to determine
what can be extracted. There is, however, no linkage between the message that arrives and the
opcode of the last command that the script executed when determining if the script should start
processing again (Section C). See sample scripts for a description of some classic problems.

A Is the message a failure message?
If ACS_UNIVERSAL_FAILURE_CONF or CSTA_UNIVERSAL_FAILURE_CONF:
Perform the specified error treatment, and exit this routine

B - Data extraction: If the message is a confirmation event, go to B1;
If it's an unsolicited event, go to B2:

B1 -If the incoming message is a confirmation event:
If a "makecall" confirmation:
Saves (CSTAMakeCallConfEvent_t *)buf->newCall in the array
elements indicated by save1.
If a "monitor" confirmation:
Save (CSTAMonitorConfEvent *)buf>monitorCrossRefID in the
cross reference table for the current device.
If a "conference" or "transfer" confirmation:

Date: 12/15/2009 CID: 144440
Save (CSTAConferenceCallConfEvent_t *)buf >newCall.callID
in the call ID portion of the connectionID in all
array elements indicated in save1.
Break ( Go to section C )

B2 - If the incoming message is an unsolicited event, does the cross
reference ID in the event report correspond to a monitor set by the
script? If not, the event is not used by the script interpreter. If
it is, then:

If "Delivered" event:
Save (CSTADeliveredEvent_t *)buf->connection in save2 array
elements. save2 index is not cleared
If "Established" event:
If the current opcode is "answer", "manual" or "wait", saves
(CSTAEstablishedEvent_t *)buf >establishedConnection in save1
array elements. save1 index is not cleared.
If "Diverted" event:
Saves (CSTADivertedEvent_t *)buf->connection in save1 array
elements. save1 index is cleared.
If "Network_reached" event:
Saves (CSTANetworkReachedEvent_t *)buf>connection in save2
array elements. save2 index is cleared.
If "Queued" event:
Saves (CSTAQueuedEvent_t *)buf->queuedConnection in save1
If "Service_initiated" event:
Saves (CSTAServiceInitiatedEvent_t *)buf->initiatedConnection
in save1 array elements. save1 index is cleared.
If "Held" event:
If the current opcode is not "HOLD", returns else saves
(CSTAHeldEvent_t *)buf->heldConnection in save1 array
elements. save1 index is cleared.
If "Retrieve" event:
If the current opcode is not "Retrieve", returns else saves
(CSTARetrievedEvent_t *)buf->retrievedConnection in save1

C - Wakeup Script?: Is this message one that is supposed to "wakeup" the
script? If so, stop the error timer, initialize opcode parameters and
read the next line of the script.
7.2 Potential Pitfalls
7.2.1 Outstanding Confirmation Events
Any confirmation event received is assumed to be for the opcode just executed. If the event
specified by the wait-condition is a confirmation event, this message causes the script to
continue. Information is not saved as expected.
Problems may show up immediately or much further down the line.
Consider the following example:


REQUEST Clear Call Call ID: 275 Device ID: 55851
EVENT Call Cleared Call ID: 275 Cross Ref ID:4

Date: 12/15/2009 CID: 144440
monitor_dev 55850

REQUEST Monitor Device Device ID: 55850
CONFIRM Clear Call

In this example the "clear call" request was waiting for the "call cleared" event which came in
before the CSTA Clear Call confirmation event. (See pitfall 7.2.3 for more details.) When the
confirmation did arrive, it satisfied the wait condition for the "monitor device" command.
Unfortunately, the cross reference ID which should have been in the monitor device confirmation
message is lost, causing later attempts to stop the monitor to fail.
7.2.2 Event Ordering
The order in which messages are returned to the TSAPI Exerciser is not guaranteed. Scripts
must be written to take this possibility into account. Below is an example of how the order of the
returned messages differs between two iterations of the same script.
(The script is, obviously, the same in both cases.)
Pass 1:

REQUEST Clear Connection Call ID: 237 Device ID: 55853
EVENT Connection Cleared Call ID: 242 Device ID: 55852 XRef ID:6
Pass 2:

REQUEST Clear Connection Call ID: 270 DevID: 55853
7.2.3 Call Cleared Events in Conference Scenarios
Conference calls often lead to problems especially if they involve ACDs or VDNs. When a call
is conferenced by the PBX, the call ID of the held call is changed to that of the active call so that
all parties on the call have the same call ID. If the held device is a monitored ACD or VDN, a
"call cleared" event is sent containing the held call ID.

REQUEST Conference: Held Call ID: 272 Device ID: 55851
Active: Call ID: 275 Device ID: 55851
CONFIRM Conference ID: 275 Device ID: 55851
Call ID: 275, Static Device ID 55850
EVENT Conference: Held Call: Call ID: 272 Dev ID: 55851
Old Active Call: Call ID: 275 Device ID: 55851
=> EVENT Call Cleared Call ID: 272 Device ID: 0 Cross Ref ID: 3
REQUEST Clear Call Call ID: 275 Device ID: 55851
EVENT Call Cleared Call ID: 275 Device ID: 0 Cross Ref ID: 4
CONFIRM Clear Call

Date: 12/15/2009 CID: 144440

The new call ID returned in the conference list of the "conference" or "transfer" confirmations
should be used to overwrite the old call IDs in all the saved connection IDs on the call.
Logically "OR" together all the array indices of all the connection IDs of the parties on the call.

makecall 4441 4442 EST stop ID1 ID2
hold ID2
makecall 4442 4443 EST stop ID3
conference ID2 ID3 wait_def stop ID1 | ID2 | ID3

7.2.4 Save Field Behavior
Data may be extracted from any unsolicited event that is received after the opcode is executed
and before the wait-condition event causes the script to continue.
Data from all unsolicited events except the "Delivered" and "Network_reached" events are saved
in the array elements indicated by save1. If this field is zero, no data is saved. The default
value for save1 is zero.
Data from "Delivered" and "Network_reached" events are saved in the array elements indicated
by save2. If this field is zero, no data is saved. The default value for save2 is zero.
7.2.5 Save Field Initialization
All save fields are initialized when a new opcode is executed. If the expected event for the
opcode on a particular line does not arrive until after the opcode on the following line is
executed, the results are unpredictable. If there are no save fields on the following line, no data
is retrieved and those array elements that should have been updated with the new data contain
old data. If save fields are indicated the following line, the data is saved in these array elements
and may be overwritten by subsequent data or, worse, may cause the save1 value to be cleared,
leaving incorrect data in the array elements.
7.2.6 Wait Conditions and Save Fields
It is most important to remember that there is no explicit connection between the "wait-
condition" event and the save fields. Indicating a wait-condition event to be a specific
message, e.g. a "Delivered" event, does not mean that data is retrieved from that, and only that,
"delivered" event. The wait-condition event signals the end of saving data for that opcode. See
the conferencing example in the Sample Scripts section.
8. Sample Scripts
8.1 Simple Call
The output displayed below is the result of a simple script, displayed in the second column. Two
devices are monitored and a call between the two monitored devices initiated. When the call has
been established, it is put on hold at the called device. The held call is retrieved and, finally, the
called device hangs up.

Date: 12/15/2009 CID: 144440
The commands executed by the script interpreter are interleaved with the actual output to show
how the interpreter works.
Notice that the "makecall" request waits for an "established" event before proceeding. This
implies that the Auto-Answer feature is enabled at the called device. The "service initiated" and
two "delivered" events are processed before the "established" event causes script processing to
continue.
Notice also that there is a second "established" event that is received after the "hold" request has
been made. Processing continues after the first message satisfying the wait condition is received.
If any data is needed from messages arriving after this message, the script must do something to
retrieve it.

****************** SCRIPT HAS STARTED ****************

monitor_dev 4441


monitor_dev 4442



REQUEST Make Call Calling: 4441 Called: 4442
CONFIRM Make Call Call ID: 3 Device ID: 4441
EVENT Service Init Call ID: 3 Device ID: 4441
EVENT Delivered Call ID: 3 Device ID: 4442
EVENT Established Call ID: 3 Device ID: 4442

hold ID2

REQUEST Hold Call Call ID: 3 Device ID: 4442
EVENT Established Call ID: 3 Device ID: 4442
CONFIRM Hold Call
EVENT Held Call ID: 3 Device ID: 4442

retrieve ID2

REQUEST Retrieve Call Call ID: 3 Device ID: 4442
EVENT Held Call ID: 3 Device ID: 4442
CONFIRM Retrieve Call
EVENT Retrieved Call ID: 3 Device ID: 4442

clear_conn ID2

REQUEST Clear Connection Call ID: 3 Dev: 4442
EVENT Retrieved Call ID: 3 Device ID: 4442

Date: 12/15/2009 CID: 144440
monitor_stop 4441


monitor_stop 4442

***************** SCRIPT HAS COMPLETED ***************

If the script had used the default wait condition for the "makecall" request, a failure would have
occurred. Recall that the default wait condition for the "makecall" request includes receipt of the
"failed", "delivered", "queued" and "network reached" events. The script would have continued
processing when it received the first "delivered" event and attempted to put the call at the called
device on hold. The connection ID would be correct, but since the "established" event had not
been received, the call would still be alerting at the device. Thus, the "hold" request would have
failed because the holding device would have in an incorrect state. This is illustrated below:

makecall 4441 4442 WAIT_DEF stop ID1 ID2

REQUEST Make Call Calling: 4441 Called: 4442
EVENT Service Initiated Call ID: 4 Device ID:4441

hold ID2

CONFIRM Failure INVALID_CONNECTION_ID_FOR_ACTIVE_CALL
**************** SCRIPT HAS BEEN ABORTED **************

To work properly, the makecall request in the script should wait for the "established" event.
Note: When the script aborts, the monitors for the script are stopped automatically. This
happens only on an abort. If the script ends normally, any active monitors will not be stopped
automatically.
Note: When the script aborts, the call that was placed from 4441 to 4442 is still active. If the
script is rerun, it would fail because the resources are busy.
8.2 Conference Call Script
The following example shows how a conference call can be set up in a script. The script
assumes that the Auto-Answer feature is enabled at extensions 4442 and 4443.

monitor_dev 4442


Date: 12/15/2009 CID: 144440


REQUEST Make Call Calling Device: 4441 Called Device:4442
EVENT Delivered Call ID: 13 Device ID: 4442 CrossRef ID:1004
EVENT Established Call ID: 13 Device ID: 4442 Cross Ref ID:1004

hold ID2

CONFIRM Hold Call
EVENT Held Call ID: 13 Device ID: 4442 Cross Ref ID: 1004

makecall 4442 4443 EST stop ID3

REQUEST Make Call Calling Device: 4442 Called Device:4443
EVENT Service Initiated Call ID: 14 Device ID:4442 XRef ID:1004
EVENT Delivered Call ID: 14 Device ID: 4443 CrossRef ID: 1004
EVENT Established Call ID: 14 Device ID: 4443 Cross Ref ID: 1004

conference ID2 ID3 wait_def stop ID1|ID2|ID3

REQUEST Conference Call: Held Call: Call ID: 13 DeviceID: 4442
CONFIRM Conference Call Call ID: 15 Device ID: 4442
EVENT Conference: Old Held Call: Call ID: 13 Device ID: 4442

clear_call ID2 conn_cl

CONFIRM Clear Call

The initial "makecall" request waits for the "established" event before proceeding. Therefore,
the "makecall" confirmation, "delivered" and "established" events are received before the script
resumes.
The "makecall" confirmation message contains the connection ID of the calling device (4441)
and is saved in ID1. The connection ID of the called device (4442) is retrieved from the
"delivered" event and saved in ID2. Neither save index is cleared, but no information is
retrieved from the "established" event because the current opcode, "makecall", is not the correct
type.
When the script continues, it requests that the call be put on hold at the device in ID2 (4442).
When the "held" event is received (the default wait for a "hold" request), a second "makecall" is
made from 4442 to 4443. The connection ID, from the confirmation message, of the calling
device (4442) is saved in the save1 variable - ID3. This is overwritten by the connection ID in
the "service initiated" event, but, since the values are the same, the end result is that ID3 contains
the connection ID of the calling device. The connection ID of the called device (4443) is not
saved because the save2 field is 0.
The "conference" request conferences all three devices together. The new call ID is saved in all
three connection IDs, ID1, ID2 and ID3.
Note that, in this example, a request to clear the connection at 4443 would not work because the
required connection ID is not known.

TSAPI Exerciser Scripting Instruct Issue2

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

TSAPI Exerciser Scripting Instruct Issue2

Diunggah oleh

Hak Cipta:

Format Tersedia

Editor: J . Gresh 2009 Avaya Inc. All Rights Reserved.

Anda mungkin juga menyukai