Siemens HiPath optiPoint 410 Instruction Manual

HiPath
optiPoint application module
XML Applications
Developer’s Guide

For internal distribution only
May 18, 2006
1optiPoint application module - XML Applications, Developer’s Guide
bkIVZ.fm
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Functions and Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1 Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2 Basic Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Push Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.4 Using Predefined Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 Installation and Starting the Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1 Generating a Program on the Telephone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2 Starting the Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4 XML Object Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.1 Phone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3 Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.4 Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.5 Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.6 Alert. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.7 List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.8 TextBox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.9 Ticker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.10 Hidden. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.11 Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.12 Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5 Push Technology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
6 Appendix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.1 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.2 XML Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

c01.fm
18. May 2006
optiPoint application module - XML Applications, Developer’s Guide 2
Introduction
Overview
1 Introduction
1.1 Overview
In conjunction with the optiPoint application module, users of Siemens optiPoint 410/420 410/
420 IP telephones have simple access to many applications.
In addition to local services such as the integrated address book, these applications also in-
clude those that can live anywhere on the network and which can be just as easily accessed
thanks to the existing IP connection.
The optiPoint application module uses not only a standard WAP browser for Internet or intranet
contents conforming to the WML standard, it can also be integrated with numerous application-
specific solutions.
The application platform for the Siemens optiPoint telephones described here represents a new
angle in the convergence between telephony and web applications. An XML interface makes it
possible, using only a suitably-equipped telephone, to interact with applications in the back of-
fice. Since XML and HTTP serve as interfaces, technologies normally used for web applications
can also be used for server-side applications: Apache, Microsoft IIS, Tomcat, Java servlets,
J S P, P H P, e t c .
An important characteristic of convergence is that the server-side application can initiate the
transfer of data to the application platform of the telephone, just as a phone not only makes calls
but also receives them.
In this way, you can extend the range of application of your optiPoint IP phone considerably and,
at the same time, optimize access to your applications using a highly available gateway – inde-
pendent of or as an addition to your other access options such as computer installations.
The XML communication interface is available in the firmware for the device types
optiPoint 410/420 standard and advance in the corenet IP variant (HFA). The application type
described here distinguishes itself in terms of installation, basic functionality and range of ap-
plication from Java MIDlets, which always function as stand-alone applications.
This document describes the XML interface as well as error handling for invalid XML data. In
view of this, note that error handling is not visible to the user. If some of the elements in an ob-
ject are missing, the existing elements are displayed anyway. When developing applications,
validation of the XML documents using an XML schema is recommended (see Section 6.2,
"XML Schema").
This document is meant for use by Siemens internal developers as well as by third party appli-
cation developers. It contains the following sections:
• Functions and Features
• Installation and Starting the Program

Introduction
18. May 2006
3optiPoint application module - XML Applications, Developer’s Guide
c01.fm
Prerequisites
• XML Object Reference
• Push Technology
• Appendix
1.2 Prerequisites
The following components and tools are required for developing applications for the application
platform:
1. optiPoint phone, type optiPoint 410 standard/advance or optiPoint 420 standard/advance
2. A DSM (display module) or APM (application module) must be connected to the telephone.
3. Infrastructure:
• IP network to which the IP phone is connected
• Web browser for creating programs for the telephone using the Web Based Manager
(e. g., Internet Explorer, Firefox, Opera)
• Web server for sending the XML data to the IP phone (e. g., Microsoft IIS, Apache,
Tomcat). It is important that the server is configured with the MIME type text/xml.
• For interactive applications: Application platform on the server for dynamically gener-
ating XML data (e. g., Java servlet, ASP, CGI, PHP).
4. XML editor:
An XML editor that can validate the documents using XML schema is recommended (e. g.,
Oxygen, XMLWriter, EditiX, XMLSpy).
5. For developing Java servlets: A suitable development environment, e. g., Eclipse, Net-
Beans, IBM Websphere Studio.

c01.fm
18. May 2006
optiPoint application module - XML Applications, Developer’s Guide 4
Functions and Features
Infrastructure
2 Functions and Features
2.1 Infrastructure
The following diagram shows the lines of communication between the various components:
LAN
optiPoint optiPoint
optiPoint
Application Server /
Web Server
optiPoint
application module

Functions and Features
18. May 2006
5optiPoint application module - XML Applications, Developer’s Guide
c01.fm
Basic Functionality
2.2 Basic Functionality
The following diagram shows the basic functions of the application:
The functional process of an application can be described as follows:
1. The user installs an application on the optiPoint phone.
2. The user calls an application from the list of programs installed.
3. The phone calls the URL of the program on the server.
4. The server-side program generates an XML document that corresponds to the specified
XML schema (see Section 6.2, "XML Schema"). The web server sends the XML document
to the phone via an HTTP connection.
5. The XML document is parsed and shown on the display of the DSM or the APM.
6. The user enters commands and data via the touchscreen or the keyboard of the DSM or
the APM.
7. The user’s commands and entries are detected by listeners in the telephone software.
8. The phone passes the user entries as key/value pairs on to the server-side program.
>When the program starts, the HTTP GET request that requests the XML document
from the server also contains the IP address and the telephone number of the IP
phone, e.g., ipaddress=137.223.238.174&phonenumber=2256.
IP Phone 410/420
DSM or APM
Display
Keypad XML
Parser
Java
Environment
XML
Application
Business
Logic
XML
HTTP/HTTPS Webserver
Server

c01.fm
18. May 2006
optiPoint application module - XML Applications, Developer’s Guide 6
Functions and Features
Push Technology
2.3 Push Technology
Push technology makes it possible for the program to be started and, therefore, the data to be
pushed from the server-side.
With Push technology, a program on the server calls a specified URL for the IP phone and
prompts it to load a specific XML document from a specific server. After this, the XML document
is also parsed and displayed as in normal operation.
2.4 Using Predefined Images
In addition to being able to link any images saved on a server within an XML document, prepre-
pared images, for example, for buttons, are also available. These images are already included
in the telephone software. One advantage of this is reduced data traffic and, therefore, in-
creased application speed. For more information about linking images, see Section 4.12, "Im-
age".

Installation and Starting the Program
18. May 2006
7optiPoint application module - XML Applications, Developer’s Guide
c01.fm
Generating a Program on the Telephone
3 Installation and Starting the Program
3.1 Generating a Program on the Telephone
Programs for the application platform described here are generated using the Web Based Man-
ager. For this, the following steps are necessary:
1. Enter the IP address of the telephone in the web browser. The introduction page appears.
2. Go to Administration and enter the administrator password. In the Administration menu,
select New Program. The following input screen is displayed:
3. Now enter the following information:
•Display Name: The name of the program as it appears in the program menu on the
APM or the DSM. The display name must meet the following criteria:
• It must be a unique name on the telephone.
• It cannot contain ’^’ characters.
• It cannot be empty.
• It cannot be longer than 100 characters.
•Application Name: This is used internally by the application to identify the program
running on the telephone. The application name must meet the following criteria:
• It must be a unique name on the telephone.
• It cannot contain any non-alphanumeric characters.
• The first character must be a letter.
• It cannot be empty.

c01.fm
18. May 2006
optiPoint application module - XML Applications, Developer’s Guide 8
Installation and Starting the Program
Generating a Program on the Telephone
• It cannot be longer than 20 characters.
•Server Address: The IP address or domain/host name of the server (example,
www.domain.de) that provides the application or the XML document.
•Server Port Number: The number of the port that the server uses to provide the ap-
plication or the XML document.
•Program Name on Server: The relative path to the servlet or to the first XML page of
the application on the server. The relative path refers to the root directory for docu-
ments on the web server, e. g., for Apache htdocs. For instance, if an XML document
is saved in C:\programs\Apache Group\Apache\htdocs\ipp\ippTest.xml, the entry
is ipp/ippTest.xml. The information cannot be longer than 100 characters.
•Use Proxy: This specifies whether a proxy should be used. If Yes has been set, the
program uses the default Java proxy. This can be configured in the Web Based Man-
ager under Administration > Applications > Java. In order to use a proxy, not only
must the telephone be visible to the proxy but also the server.
4. Click the Create Program button to start generating the program.
3.1.1 Configuring and Deleting Programs Using the Web Based Man-
ager
Complete the following steps to configure or delete a program:
1. Enter the IP address of the telephone in the web browser. The introduction page appears.
2. Go to Administration and enter the administrator password. In the Administration menu,
select Configure/Delete Program. The following input screen is displayed:
>The information entered is validated after being sent. If the information is incorrect,
the program is not generated and an error message is returned.

Installation and Starting the Program
18. May 2006
9optiPoint application module - XML Applications, Developer’s Guide
c01.fm
Starting the Program
select the program that you would like to configure or delete from the Program List pull-
down menu.
If you would like to reconfigure the program, change the respective parameters. For more
information about these parameters, see Section 3, "Installation and Starting the Program".
Click the Submit Changes button to confirm the changes.
If you would like to delete the program, click the Delete Program button.
3.2 Starting the Program
If the user starts a program on the telephone, the application calls the URL of the program from
its end on the server.
The telephone tells the server its IP address and telephone number using key/value pairs within
the URL. The key/value pairs are sent in the following format:
ipaddress=<telephone-IP-address>&phonenumber=<telephone number>

c01.fm
18. May 2006
optiPoint application module - XML Applications, Developer’s Guide 10
XML Object Reference
Starting the Program
4 XML Object Reference
This chapter describes the usage, content and error handling for the individual XML objects.
The objects are comprised of a main element, its attributes and one or more child elements and
their attributes. The names of the basic XML elements are prefixed with "Ipp" which stands for
"IP phone", for example, "IppAction".
The following table gives an overview of the individual objects and their function:
>Examples of the individual objects are provided. You will find the associated XML
files under:
http://siemens.com/hipath
Category Object Functional Description
Basic XML
structure
Phone Optional root element; for future objects outside of the
display
Display root element
Navigation Command (BACK,
NEXT or UPDATE)
BACK: Leads to the screen displayed previously
SCREEN: Leads to a specific screen
UPDATE: Reloads the screen from the server
Form Form Form for sending the contents of data fields to the serv-
er
Message win-
dow
Alert Temporarily appears over the currently displayed
screen and contains a message
Ticker Ticker Ticker text in the title bar
Text, layout,
image
Form/StringItem Shows text on the display
Form/Spacer Generates a line break
Image Links an image file
Form/ImageItem Positions an image
Selection lists List List of selectable options
Form/ChoiceGroup List of selectable options
Data input TextBox Text input field with multiple lines
Form/TextField Text input field with a single line
Form/DateField Date input field
Form/Gauge (inter-
active)
Entry of a numerical value using a horizontal slider
Table 4-1

XML Object Reference
18. May 2006
11 optiPoint application module - XML Applications, Developer’s Guide
c01.fm
Phone
4.1 Phone
If IppPhone is used as the root element, it is possible to integrate special objects in the XML
application but not shown on the display. This type of object will be available in future versions
of the application platform. Using this in current XML applications has the advantage of allowing
applications to be easily extended with new objects in the future.
Using IppPhone as the root element is, therefore, not mandatory; IppDisplay (see Section
4.2, "Display") can also be the root element of an XML application.
Syntax
<IppPhone>
<IppDisplay/>
<IppDisplay/>
</IppPhone>
Hidden data
transfer
Hidden Invisible field for transmitting data between telephone
and server
Visualization
of chronologi-
cal processes
Form/Gauge (not in-
teractive)
Horizontal bar that grows with adjustable speed
Sending data
to the server
Command (SE-
LECT)
The data contained in the entry fields on the screen are
sent to the server.
Form/Button Sends the data saved in attributes to the server
Telephony Action (MAKE-
CALL)
Initiates a call to a specific telephone number
Category Object Functional Description
Ta b l e 4 - 1

c01.fm
18. May 2006
optiPoint application module - XML Applications, Developer’s Guide 12
XML Object Reference
Display
4.2 Display
This object enables multiple screens within a single XML document. A screen corresponds to
the content that is simultaneously shown on the display, comparable to a web page. According-
ly, the IppScreen element functions as the root element of an XML document and, therefore,
as the container for various screen objects, comparable to cards in an WML document.
Syntax
<IppDisplay>
<IppScreen/>
<IppScreen/>
</IppDisplay>
4.3 Screen
The IppScreen element serves as a container for additional specified contents. The ID at-
tribute enables switching between different screens.
The following attributes are available to the IppScreen element:
Attribute Value Functionality/Remarks
ID
(optional)
ID of the
screen ele-
ment
(integer)
Enables referencing of the screen object, so that the
screen can be accessed directly.
HiddenCount
(mandatory)
Number of
Hidden objects
All Hidden objects are displayed.
0 All Hidden objects are ignored.
A number
greater than
the actual
number of Hid-
den objects
All the Hidden objects that exceed the number indicated
are ignored.

XML Object Reference
18. May 2006
13 optiPoint application module - XML Applications, Developer’s Guide
c01.fm
Screen
Syntax
<IppScreen ID="i" HiddenCount="m" CommandCount="n">
<IppAction/>
<IppCommand/>
<IppAlert/>
<IppList/>
<IppTextBox/>
<IppTicker/>
<IppHidden/>
<IppForm/>
<Image/>
</IppScreen>
IppCommand
(mandatory)
Number of
Command ob-
jects
All Command objects are displayed.
0 All Command elements are ignored.
A number
greater than
the actual
number of
Command ob-
jects
All the Command elements that exceed the number in-
dicated are ignored.

c01.fm
18. May 2006
optiPoint application module - XML Applications, Developer’s Guide 14
XML Object Reference
Action
4.4 Action
The Action object represents a specific task for the phone. This task is specified in the Type
attribute. Currently, only the MAKECALL value, which triggers a telephone call, is available.
The following attributes are available to the IppAction element:
Syntax
<IppAction Type="MAKECALL">
<Number> </Number>
</IppAction>
Child elements
•Number
The telephone number to be dialed.
Example
<?xml version="1.0" encoding="UTF-8" ?>
<IppDisplay>
<IppScreen ID="1" HiddenCount="0" CommandCount="0">
<IppAlert Type="CONFIRMATION" Delay="FOREVER">
<Title>IppAction</Title>
<Text>Dialing a number...</Text>
<Image></Image>
</IppAlert>
<IppAction Type="MAKECALL">
<Number>12345</Number>
</IppAction>
</IppScreen>
</IppDisplay>
Attribute Value Function
TYPE
(mandatory)
MAKECALL A call made to the telephone number specified in the
child element <Number> is pushed.
>The action type "MAKECALL" can be executed on the models Siemens
optiPoint 410/420 410/420 standard and advance in the SIP and in the HFA variants.

XML Object Reference
18. May 2006
15 optiPoint application module - XML Applications, Developer’s Guide
c01.fm
Command
4.5 Command
This object generates a softkey on the lower edge of the display, comparable to the do element
in WML. A maximum of two softkeys can be displayed simultaneously on a screen. If there are
more than two Command elements, the second softkey is labeled as "Menu" and not given a
yellow background; when it is selected, it opens a new screen on which the user can select from
the remaining Command objects.
The following attributes are available to the IppCommand element:
Attribute Value Function
Type
(mandatory)
SELECT This transmits the key/value pairs from the current form
to the URL indicated.
BACK Switches to the screen displayed previously. When this
is selected, the cached version is used.
If there is only a single screen in the XML document, no
softkey is generated.
UPDATE Switches to the screen displayed previously. The docu-
ment is then reloaded from the server.
SCREEN Switches to the specified screen.
If the data in the ScreenID child element are missing
or invalid, the current screen will continue to be dis-
played.
Priority
(optional)
Priority (inte-
ger)
This determines the order of the Command objects,
whereby 0 represents the one with the highest priority.
Auto
(optional)
Total duration
in seconds
The Command object is automatically executed after
the specified time, that is, without the user doing any-
thing. If multiple Command objects containing the Auto
attribute exist, the one that is set for the shortest total
duration is executed. This means that only one com-
mand per screen is executed automatically.
Key
(optional)
Key The key for the key/value pair that is sent to the server.
Value
(optional)
Value The value for the key/value pair that is sent to the server.

c01.fm
18. May 2006
optiPoint application module - XML Applications, Developer’s Guide 16
XML Object Reference
Command
Syntax
<IppCommand Type="SELECT|BACK|UPDATE|SCREEN" Priority="[Number]" Au-
to="[Number]" Key="[Key]" Value="[Value]">
<Label> </Label>
<ScreenID> </ScreenID>
</IppCommand>
Child elements
• Label
Contains the label for the softkey.
• ScreenID
Indicates which screen should be accessed next.
Example
<?xml version="1.0" encoding="UTF-8" ?>
<IppDisplay>
<IppScreen ID="1" HiddenCount="0" CommandCount="1">
<IppTextBox MaxSize="30" Constraint="ANY" Default="TEXT"
Key="TB1">
<Title>Textbox Title</Title>
<Text>add your text here...</Text>
<Url>http://subdomain.domain/path/program</Url>
</IppTextBox>
<IppCommand Type="SELECT" Priority="0">
<Label>Select</Label>
<ScreenID>1</ScreenID>
</IppCommand>
</IppScreen>
</IppDisplay>
>Multiple occurrences of a type can appear on a screen as long as each occurrence
is uniquely distinguishable. If two or more occurrences are not distinguishable from
each other, the second as well as any further occurrences are ignored.
>If the Type attribute is missing or has an invalid value, it is not displayed. If the <La-
bel> child element is missing, a softkey is displayed with the English language data
for the command type instead of a label.

XML Object Reference
18. May 2006
17 optiPoint application module - XML Applications, Developer’s Guide
c01.fm
Alert
Screenshot
4.6 Alert
An Alert is a message window that temporarily replaces the currently displayed screen. Differ-
ent types of Alert can be selected using the Type attribute. Title, text as well as an image can
be specified in the child elements.
The following attributes are available to the IppAlert element:
Attribute Value Functionality/Remarks
Type
(optional)
ALARM No specific properties are perceptible by the user.
CONFIRMATION No specific properties are perceptible by the user.
ERROR Default value. No specific properties are perceptible by
the user.
INFO No specific properties are perceptible by the user.
WARNING No specific properties are perceptible by the user.
Delay
(optional)
Timeout in millisec-
onds
After the specified time elapses, the Alert disappears
and the previously displayed screen reappears.
FOREVER Default value. The display of the Alert can be deactivat-
ed only by the user.

c01.fm
18. May 2006
optiPoint application module - XML Applications, Developer’s Guide 18
XML Object Reference
Alert
Syntax
<IppAlert Type="ALARM|CONFIRMATION|INFO|WARNING" Delay="[Number]|FOR-
EVER">
<Title> </Title>
<Text> </Text>
<Image Cache="n"> </Image>
</IppAlert>
Child elements
•Title
The title of the Alert is displayed in the title bar.
•Text
Text in an Alert.
•Image
The image for the Alert. For more information about the Image tag, see Section 4.12, "Image".

XML Object Reference
18. May 2006
19 optiPoint application module - XML Applications, Developer’s Guide
c01.fm
Alert
Example
<?xml version="1.0" encoding="UTF-8" ?>
<IppDisplay>
<IppScreen ID="1" HiddenCount="0" CommandCount="1">
<IppForm ItemCount="1">
<Title>Test Confirmation Alert</Title>
<Url>http://subdomain.domain/path/program</Url>
<IppStringItem>
<Label>Press Alert</Label>
<Text>for Confirmation Alert</Text>
</IppStringItem>
</IppForm>
<IppCommand Type="SCREEN" Priority="0">
<Label>Alert</Label>
<ScreenID>2</ScreenID>
</IppCommand>
</IppScreen>
<IppScreen ID="2" HiddenCount="0" CommandCount="0">
<IppAlert Type="CONFIRMATION" Delay="FOREVER">
<Title>Alert</Title>
<Text>Alert1</Text>
<Image></Image>
</IppAlert>
</IppScreen>
</IppDisplay>
Screenshot