Seminar paper

iPhone App
clusterinfo.at

Stefan Almer, Bsc

stefan.almer@student.tugraz.at

Graz University of Technology

Institute for Information Systems and Computer Media

Adviser: Dipl.-Ing. Dr.techn. Josef Kolbitsch

Graz, September 2010

 Abstract

Mobile devices such as Apple’s iPhone or various Google Android driven devices are
getting increasingly popular. With such devices and the possibility to access the internet
wirelessly it is possible to gain information everywhere on earth. For representing infor-
mation so called Apps (mobile applications) are used. Such applications are fast, easy to
use and often fit just one special purpose.
This paper deals with the implementation of the iPhone application clusterinfo.at. This
app represents the mobile userinterface to the existing web portal. To access the infor-
mation a REST based webservice API has been developed which provides various services
like searching. Every request is covered in a result set which only contains metadata about
the information found. The client needs to post a second request with the result set to get
all records.

Keywords iphone, rest webservice, clusterinfo, human technology styria, xml

1
Statutory Declaration
I declare that I have authored this thesis independently, that I have not used other than
the declared sources / resources, and that I have explicitly marked all material which has been
quoted either literally or by content from the used sources.

Date Signature

2
 Contents

Contents
Contents i

List of Figures ii

List of Listings iii

1 Introduction 1

2 Implementation 2
2.1 Server-Side API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1.1 Categories for section: /getBrowseCategories . . . . . . . . . . . . . . 3
2.1.2 Search: /search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1.3 Result set: /getResultSet . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1.4 User in role: /isUserInRole . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.5 Promoted events: /getPromotedEvents . . . . . . . . . . . . . . . . . . 8
2.1.6 Detail: /getDetail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.1.7 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.2 Client-Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.2.1 Newsticker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3 Functionality of the iPhone application 14

3.1 Sections/Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2 Login - Cluster members . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3 Records details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.4 Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.5 Newsticker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

i
 List of Figures

List of Figures
1 iPhone - Server: Request - Response example . . . . . . . . . . . . . . . . . . . 12
2 Simple class-diagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3 Section view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4 Category view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5 Section "person" - user not logged in . . . . . . . . . . . . . . . . . . . . . . . . 15
6 Wrong password or username . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7 User logged in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
8 Company . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
9 Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
10 Person . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
11 Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
12 Search in section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
13 Search in category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
14 Static message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
15 Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
16 Event detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

ii
 Listings

Listings
1 Example response for all categories in section "event". . . . . . . . . . . . . . . 3
2 Result-Set for records in category "Kongress". . . . . . . . . . . . . . . . . . . . 5
3 Result-Set for search in category. . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4 Result-Set for search in section. . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5 Response from isUserInRole, the user has no rights. . . . . . . . . . . . . . . . 7
6 Promoted events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
7 Details for "event" with ID 415 . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
8 No/invalid API key provided . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
9 Wrong/too few arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
10 Access of secure service in public environment . . . . . . . . . . . . . . . . . . . 11

iii
 1 Introduction

1 Introduction
The clusterinfo.at iPhone application is the mobile access point for the existing clusterinfo.at
web portal and CRM system. For accessing the portal a completely new REST-API has been
developed which provides direct access to the database.
Like the web portal, the App allows the user to search the public database.
Further features:

• Search in section: company, event, person

• Search in category

• Show address in map

• Write in-app email

• Open links in browser

• Call telephone numbers

The section "person" is only available for cluster members.

This paper also provides a detailed documentation of the implemented REST webservice
API, the implementation of the client and an overview of the functionality of the application.

1
 2 Implementation

2 Implementation
The CIS (clusterinformation system) provides a REST webservice to access all information of
the clustersystem. The webservice provides public and secure (HTTP-Basic-Auth, username/-
password) access over SSL (secure socket layer). The service responds with an XML document
encoded in ISO-8859-1 over the following URLs:

• Public: https://www.clusterinfo.at/mobile/services/<service>

• Secure: https://www.clusterinfo.at/mobile/services/secure/<service>

For several requests (e.g. /search) the webservice only returns a result set. In this case,
the webservice executes a query and returns an XML response with "metadata" about the
search like the "set id" generated on the server and the number of records found.
The set contains all records found (on the server). The results (records) can be requested
with another service later on - this means that not all records are returned intermediately to the
client. This mechanism has several advantages: fast and small response, instant information
about the search, "browsing" through the set or only get a range of records.

2.1 Server-Side API

The server-side API provides the following services:

• /getBrowseCategories (see 2.1.1)

• /getResultSet (see 2.1.3)

• /isUserInRole (see 2.1.4)

• /search (see 2.1.2)

• /getPromotedEvents (see 2.1.5)

• /getDetail (see 2.1.6)

2
 2 Implementation

All services can be accessed either publicly or securely except /isUserInRole, which can
only be accessed securely. For every request the apiKey attribute (access token) has to be
provided to ensure an authorized access from the iPhone application.
The root node (<result>) of the XML response has the following attributes:

• status: status of the request: OK or ERROR

• searchHits: number of retrieved search results

• setId: ID of the generated set (only /search)

2.1.1 Categories for section: /getBrowseCategories

Returns the categories (with attributes FIXED/DYNAMIC) for a specific section.

Arguments:

• type: {company|person|event} (section)

Example: All categories for the section "event".

• Request: /getBrowseCategories?apiKey=1234&type=event

• Response:
1 <? xml version = " 1.0 " encoding = " ISO -8859 -1 " ? >
2 < r:result status = " OK " xmlns:r = " http: // www . healthgate . at /←-
HTSMobileResult " >
3 < r:category type = " FIXED " >
4 < r:id > 7999999999999001 </ r:id >
5 < r:catName > Kongress </ r:catName >
6 </ r:category >
7 < r:category type = " FIXED " >
8 < r:id > 7999999999999002 </ r:id >
9

10 < r:catName > Seminar </ r:catName >

3
 2 Implementation

11 </ r:category >

12 < r:category type = " FIXED " >
13 < r:id > 7999999999999003 </ r:id >
14 < r:catName > Q u a l i f i z i e r u n g s w o r k s h o p </ r:catName >
15 </ r:category >
16 < r:category type = " FIXED " >
17

18 < r:id > 7999999999999004 </ r:id >

19 < r:catName > Messen </ r:catName >
20 </ r:category >
21 < r:category type = " FIXED " >
22 < r:id > 7999999999999005 </ r:id >
23 < r:catName > Fachver anstaltu ng </ r:catName >
24 </ r:category >
25

26 < r:category type = " FIXED " >

27 < r:id > 7999999999999006 </ r:id >
28 < r:catName > Fast Forward </ r:catName >
29 </ r:category >
30 < r:category type = " FIXED " >
31 < r:id > 7999999999999007 </ r:id >
32 < r:catName > Fast Forward Success </ r:catName >
33

34 </ r:category >

35 < r:category type = " FIXED " >
36 < r:id > 7999999999999008 </ r:id >
37 < r:catName > Sonstige </ r:catName >
38 </ r:category >
39 </ r:result >

Listing 1: Example response for all categories in section "event".

4
 2 Implementation

2.1.2 Search: /search

This service is the main service for searching in sections, categories and for retrieving records
in categories. Therefore the API needs several arguments:

Arguments:

• Search in section:

– type: {company|person|event} (section)

– query: search term

• Search in category:

– type: {company|person|event} (section)

– query: search term
– categoryId: ID of the category

• Records in category:

– type: {company|person|event} (section)

– categoryId: ID of the category

The service only returns a result set (see 2.1.3).

Example 1: Records in category "Kongress".

• Request: /search?categoryId=7999999999999001&type=event&apiKey=1234

• Response:
1 <? xml version = " 1.0 " encoding = " ISO -8859 -1 " ? >
2 < r:result status = " OK " resultSetId = " 1 2 8 5 2 4 8 3 1 7 9 5 7 9 1 1 4 3 1 0 7 1 3 3 " ←-
searchHits = " 2 " xmlns:r = " http: // www . healthgate . at / HTSMobileResult " / >

Listing 2: Result-Set for records in category "Kongress".

5
 2 Implementation

Example 2: Search for "zukunft" in category "Kongress".

• Request: /search?categoryId=7999999999999001&type=event&query=zukunft&apiKey=1234

• Response:
1 <? xml version = " 1.0 " encoding = " ISO -8859 -1 " ? >
2 < r:result status = " OK " resultSetId = " 1 2 8 5 2 4 8 4 5 4 2 7 9 9 1 1 4 3 1 0 7 1 3 3 " ←-
searchHits = " 1 " xmlns:r = " http: // www . healthgate . at / HTSMobileResult " / >

Listing 3: Result-Set for search in category.

Example 3: Search for "zukunft" in section "event".

• Request: /search?type=event&query=zukunft&apiKey=1234

• Response:
1 <? xml version = " 1.0 " encoding = " ISO -8859 -1 " ? >
2 < r:result status = " OK " resultSetId = " 1 2 8 5 2 4 8 5 3 2 8 6 1 9 1 1 4 3 1 0 7 1 3 3 " ←-
searchHits = " 1 " xmlns:r = " http: // www . healthgate . at / HTSMobileResult " / >

Listing 4: Result-Set for search in section.

2.1.3 Result set: /getResultSet

Returns all records from a given set in a defined range.

Arguments:

• setId: ID of the set (retrieved from the /search service)

• from: Start index

• to: End index

6
 2 Implementation

Example: Get records from set "128524852912191143107133".

• Request: /getResultSet?setId=128524852912191143107133&from=1&to=3&apiKey=1234

• Response: Records from index 1 to 3.

2.1.4 User in role: /isUserInRole

Check if the current session user has a given role - either returns true or false in the XML
response.
This is a secure service. Public access is not permitted.

Arguments:

• roleName: the role to check (e.g. "clusterRights").

Example: The current user has "clusterRights"?

• Request: /secure/isUserInRole?apiKey=1234&roleName=clusterRights

• Response:
1 <? xml version = " 1.0 " encoding = " ISO -8859 -1 " ? >
2 < r:result status = " OK " xmlns:r = " http: // www . healthgate . at /←-
HTSMobileResult " >
3 < r:userInRole > false </ r:userInRole >
4 </ r:result >

Listing 5: Response from isUserInRole, the user has no rights.

7
 2 Implementation

2.1.5 Promoted events: /getPromotedEvents

Returns all promoted events - the returned XML is equal to the response when the service
/search?type=event is requested.

Example: All promoted events.

• Request: /getPromotedEvents?apiKey=1234

• Response:
1 <? xml version = " 1.0 " encoding = " ISO -8859 -1 " ? >
2 < r:result status = " OK " searchHits = " 1 " xmlns:r = " http: // www . healthgate . at←-
/ HTSMobileResult " xmlns:e = " http: // www . healthgate . at / HTSMobileEvent " >
3 < r:event >
4 < e :v er ans ta lt ung sI d > 415 </ e :v era ns ta ltu ng sI d >
5 < e:titel > Zukunft skonfere nz 2010 - next generation </ e:titel >
6 < e: v e ra n st a lt u n gs A rt > Kongress </ e : ve r a ns t al t u ng s Ar t >
7 < e:inhalt > - Human Resources und I n n o v a t i o n s m a n a g e m e n t </←-
e:inhalt >
8 < e:veranstalter > Human . technology Styria GmbH </ e:veranstalter >
9 < e:zielpublikum / >
10 < e:sfgLink cType = " URL " / >
11 < e:eventLink cType = " URL " / >
12 < e:anfahrt / >
13 < e:gebuehrMitgl > 35 </ e:gebuehrMitgl >
14 < e: g e bu e hr N ic h t Mi t gl > 160 </ e: g eb u e hr N ic h tM i t gl >
15

16 < e:maxTeilnehmer > 2147483647 </ e:maxTeilnehmer >

17 < e:anmeldeSchluss > 20100921 </ e:anmeldeSchluss >
18 < e:hinweise / >
19 < e:datumVon > 20100923 </ e:datumVon >
20 < e:zeitVon > 09 :30 </ e:zeitVon >
21 < e:datumBis > 20100923 </ e:datumBis >
22

23 < e:zeitBis > 17 :00 </ e:zeitBis >

8
 2 Implementation

24 < e:ort > Seifenfabrik Veranstaltungszentrum ,

25 Angergasse 41 -43 , 8010 Graz </ e:ort >
26 </ r:event >
27 </ r:result >

Listing 6: Promoted events

2.1.6 Detail: /getDetail

This service provides direct access to a record (company/person/event) without requesting it

with /search and /getResultSet.

Arguments:

• recordId: ID of the record

• type: {company|person|event}

Example: Get "event" record with ID 415.

• Request: /getDetail?recordId=415&type=event&apiKey=1234

• Response:
1 <? xml version = " 1.0 " encoding = " ISO -8859 -1 " ? >
2 < r:result status = " OK " searchHits = " 1 " xmlns:r = " http: // www . healthgate . at←-
/ HTSMobileResult " xmlns:e = " http: // www . healthgate . at / HTSMobileEvent " >
3 < r:event >
4 < e :v er ans ta lt ung sI d > 415 </ e :v era ns ta ltu ng sI d >
5 < e:titel > Zukunft skonfere nz 2010 - next generation </ e:titel >
6 < e: v e ra n st a lt u n gs A rt > Kongress </ e : ve r a ns t al t u ng s Ar t >
7 < e:inhalt > - Human Resources und Innovationsmanagement , ... </←-
e:inhalt >
8

9 < e:veranstalter > Human . technology Styria GmbH </ e:veranstalter >
10 < e:zielpublikum / >

9
 2 Implementation

11 < e:sfgLink cType = " URL " / >

12 < e:eventLink cType = " URL " / >
13 < e:anfahrt / >
14 < e:gebuehrMitgl > 35 </ e:gebuehrMitgl >
15 < e: g e bu e hr N ic h t Mi t gl > 160 </ e: g eb u e hr N ic h tM i t gl >
16

17 < e:maxTeilnehmer > 2147483647 </ e:maxTeilnehmer >

18 < e:anmeldeSchluss > 20100921 </ e:anmeldeSchluss >
19 < e:hinweise / >
20 < e:datumVon > 20100923 </ e:datumVon >
21 < e:zeitVon > 09 :30 </ e:zeitVon >
22 < e:datumBis > 20100923 </ e:datumBis >
23

24 < e:zeitBis > 17 :00 </ e:zeitBis >

25 < e:ort > Seifenfabrik Veranstaltungszentrum ,
26 Angergasse 41 -43 , 8010 Graz </ e:ort >
27 </ r:event >
28 </ r:result >

Listing 7: Details for "event" with ID 415

2.1.7 Error handling

The webservice returns a number of various error messages indicated by the status attribute
("ERROR") of the <result> node.
Error messages:

• No/invalid API key provided (see listing 8)

• Wrong/too few arguments (see listing 9)

• Access of secure service in public environment (see listing 10)

10
 2 Implementation

1 < r:result status = " ERROR " >

2 < r:errorMsg > InvalidApiKey </ r:errorMsg >
3 </ r:result >

Listing 8: No/invalid API key provided

1 < r:result status = " ERROR " >

2 < r:errorMsg > InvalidArguments </ r:errorMsg >
3 </ r:result >

Listing 9: Wrong/too few arguments

1 < r:result status = " ERROR " >

2 < r:errorMsg > NoPublicAccess </ r:errorMsg >
3 </ r:result >

Listing 10: Access of secure service in public environment

11
 2 Implementation

2.2 Client-Side

Client REST-Webservice

1 Request

2 Response
cluster
information
system
3 Request

4 Response

Figure 1: iPhone - Server: Request - Response example

Figure 1 shows the main concept of performing a search request:

1. Client-Request: The client request the result set for the query, e.g. "zukunft":
/search?type=event&query=zukunft&apiKey=1234.

2. Webservice-Response: The server responds with the result set containing the set id and
the number of found records - searchHits (see listing 4 for example).

3. Client-Request: If the webservice returns searchHits > 0 the client performs the next
request to get a number of records or all records from the set
(e.g. /getResultSet?setId=128524852912191143107133&from=1&to=3&apiKey=1234)
otherwise the client does not need to perform additional requests.

4. Webservice-Response: The service returns all records belonging to the given result set.

The connection to the REST-API is handled by a delegate implementation of NSURLConnection

which is held by the specific data source of each section. The parsing is done with NSXMLParser
which fulfills the required needs.
Each section has its own data source (CISectionDataSource/CICategoryDataSource) which
implements the delegate protocol of CIURLConnection and CIParser (with all subclasses) to
handle the received data - parsing, error handling.

12
 2 Implementation

Figure 2 shows the relation between all implemented classes.

AboutViewController

CIUser CISettingsCell

clusterinfo_atAppDelegate SettingsTableViewController

PeopleSectionTableViewController

CIActivityView

CISectionTableViewController CISearchTableController CICategoryTableViewController

CITickerView
AddressAnnotation

CILoadNextCell

CIMapViewController

CIEntityTableViewController
CIDetailTableViewController

CIURLConnection

CIBaseEntity CISectionDataSource CICategoryDataSource

CICompanyEntity CIPersonEntity CIEventEntity CICategoryEntity

CIEntityParser CICategoryParser CIResultParser CIUserRoleParser CITickerMessageParser

CIParser

Figure 2: Simple class-diagram

2.2.1 Newsticker

The newsticker shows messages from a static XML-File (parsed with CITickerMessageParser)
and promoted events (service /getPromotedEvents). All messages are loaded at program
startup. If the user performs a login or logout the messages are flushed and reloaded.

13
 3 Functionality of the iPhone application

3 Functionality of the iPhone application

This section shows the functionality of the clusterinfo.at application. The following images
refer to all sections.

3.1 Sections/Categories
Figures 3 and 4 show the main view for each section and category.

Figure 3: Section view Figure 4: Category view

14
 3 Functionality of the iPhone application

3.2 Login - Cluster members

The section "person" (figure 5) is only available for cluster members. Therefore the settings
page provides the a login form (figure 7).

Figure 5: Section "person" - Figure 6: Wrong password or Figure 7: User logged

user not logged in username in

3.3 Records details

Figure 8: Company Figure 9: Event Figure 10: Person Figure 11: Address

15
 3 Functionality of the iPhone application

The following attributes of an records can be accessed:

• Address → opens map view

• Telephone number → call number

• Web address → opens browser

• Email → opens in-app email client

3.4 Search
The application provides functionality for searching a whole section as well as searching a single
category. In order to perform a search request the table needs to be scrolled down.
The application provides searching a whole section (figure 12) and searching only in a section
(figure 13) - to do this, the table need to scrolled down.

Figure 12: Search in section Figure 13: Search in category

16
 3 Functionality of the iPhone application

3.5 Newsticker
The newsticker displays promoted events (indicated by ">", figure 15) which can be touched
in order to show further details (figure 16) and static messages (figure 14).

Figure 14: Static message Figure 15: Event Figure 16: Event detail

17